@schalkneethling/calavera-skill-frontend-engineering 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schalkneethling/calavera-skill-frontend-engineering",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Frontend engineering artifact for Calavera.",
   "license": "MIT",
   "repository": {

package/payload/frontend-engineering/SKILL.md

@@ -13,7 +13,7 @@ Use this skill as the entry point for frontend work. Start with the relevant imp
 - For CSS, Sass/Less, CSS modules, scoped styles, CSS-in-JS, layout, responsive behavior, motion, colors, focus states, or selectors, read `references/css-authoring.md` and `references/css-patterns.md`.
 - For forms, authentication, untrusted input, browser storage, URLs, HTML injection, API calls, uploads, or other security-sensitive browser flows, load the `frontend-security` skill.
 - For behavior changes, accessibility checks, visual changes, or regression coverage, load the `frontend-testing` skill.
-- For a new or foundational custom-property system, load the `css-tokens` skill.
+- For a new or foundational custom-property system, load the `css-tokens` skill when it is installed; otherwise define the required tokens locally with explicit fallback values.
 
 ## Working Principles
 

package/payload/frontend-engineering/references/css-authoring.md

@@ -4,7 +4,7 @@ Guidance for writing CSS that prioritizes web standards, accessibility, performa
 
 ## Core Principles
 
-1. **Web standards first** — Use native CSS features before reaching for libraries or frameworks. No Tailwind, no CSS-in-JS unless explicitly requested.
+1. **Web standards first** — Prefer native CSS features for new implementations. Follow the project's established styling conventions, including Tailwind or CSS-in-JS, when they are already in use or explicitly required.
 2. **Accessibility as a requirement** — Ensure styles support, never hinder, assistive technologies. Respect user preferences (motion, color scheme, contrast).
 3. **Performance matters** — Minimize repaints, avoid layout thrashing, use efficient selectors.
 4. **Readable over clever** — Future maintainers (including the author) should understand the code at a glance.

package/payload/frontend-engineering/references/css-patterns.md

@@ -207,8 +207,13 @@ The Shared First approach may use more lines, but results in more maintainable,
 Custom properties can reduce repetition by keeping the property declaration shared while scoping only the value to each viewport. Use sparingly — overuse can make code harder to follow.
 
 ```css
+:root {
+  --size-16: 1rem;
+  --size-32: 2rem;
+}
+
 .Dialog-container {
-  padding-block: var(--Dialog-block-padding);
+  padding-block: var(--Dialog-block-padding, 1rem);
 }
 
 @media (width < 48rem) {

package/payload/frontend-engineering/references/semantic-html-heading-patterns.md

@@ -17,8 +17,19 @@ Make heading level a prop/parameter with a sensible default.
 
 ```jsx
 // React example
+function normalizeHeadingLevel(value, fallback) {
+  const isSupportedValue =
+    typeof value === "number" || (typeof value === "string" && /^[1-6]$/.test(value));
+  if (!isSupportedValue) {
+    return fallback;
+  }
+
+  const candidate = Number(value);
+  return Number.isInteger(candidate) && candidate >= 1 && candidate <= 6 ? candidate : fallback;
+}
+
 function Card({ title, headingLevel = 3, children }) {
-  const safeHeadingLevel = Math.min(6, Math.max(1, Number(headingLevel) || 3));
+  const safeHeadingLevel = normalizeHeadingLevel(headingLevel, 3);
   const Heading = `h${safeHeadingLevel}`;
   return (
     <article className="card">
@@ -32,7 +43,7 @@ function Card({ title, headingLevel = 3, children }) {
 ```twig
 {# Twig example #}
 {% set requested_level = heading_level|default(3) %}
-{% set heading_tag = requested_level < 1 ? 1 : requested_level > 6 ? 6 : requested_level %}
+{% set heading_tag = requested_level matches '/^[1-6]$/' ? requested_level : 3 %}
 <article class="card">
   <h{{ heading_tag }}>{{ title }}</h{{ heading_tag }}>
   {{ content }}
@@ -98,9 +109,20 @@ function CardList({ cards }) {
 Create a heading component that handles both semantic and visual concerns.
 
 ```jsx
+function normalizeHeadingLevel(value, fallback) {
+  const isSupportedValue =
+    typeof value === "number" || (typeof value === "string" && /^[1-6]$/.test(value));
+  if (!isSupportedValue) {
+    return fallback;
+  }
+
+  const candidate = Number(value);
+  return Number.isInteger(candidate) && candidate >= 1 && candidate <= 6 ? candidate : fallback;
+}
+
 function Heading({ level, visualLevel = level, children, className = "" }) {
-  const semanticLevel = Math.min(6, Math.max(1, Number(level) || 2));
-  const visualHeadingLevel = Math.min(6, Math.max(1, Number(visualLevel) || semanticLevel));
+  const semanticLevel = normalizeHeadingLevel(level, 2);
+  const visualHeadingLevel = normalizeHeadingLevel(visualLevel, semanticLevel);
   const Tag = `h${semanticLevel}`;
   const visualClass = `u-heading-${visualHeadingLevel}`;
 
@@ -131,8 +153,9 @@ Generic components inherit heading config when specialised.
 
 ```jsx
 // Generic card
+// Reuse normalizeHeadingLevel from Pattern 1.
 function Card({ title, headingLevel = 3, headingClass, children }) {
-  const safeHeadingLevel = Math.min(6, Math.max(1, Number(headingLevel) || 3));
+  const safeHeadingLevel = normalizeHeadingLevel(headingLevel, 3);
   const Heading = `h${safeHeadingLevel}`;
   return (
     <article className="card">

package/payload/frontend-engineering/references/semantic-html.md

@@ -87,7 +87,7 @@ Visual styling and semantic meaning are related but not coupled. CSS classes bri
 
 ### Skip Navigation Links
 
-Skip links let keyboard and screen reader users bypass repeated navigation blocks and jump directly to meaningful content. They are required on any page with a navigation block or other repeated content before the main content.
+Skip links are the recommended default for letting keyboard users bypass repeated navigation and jump directly to meaningful content. WCAG 2.4.1 requires a bypass mechanism for repeated blocks; depending on the page structure, suitable headings, landmarks, or another mechanism may also satisfy that requirement.
 
 Place skip links as the **first focusable element** in `<body>`. They can be visually hidden and revealed on focus:
 
@@ -128,17 +128,17 @@ Place skip links as the **first focusable element** in `<body>`. They can be vis
 
 Use landmark elements to convey page structure:
 
-| Element   | Use When                     | Notes                                                                            |
-| --------- | ---------------------------- | -------------------------------------------------------------------------------- |
-| `header`  | Page or section header       | Can appear multiple times in different contexts                                  |
-| `footer`  | Page or section footer       | Contact info, copyright, related links                                           |
-| `nav`     | Navigation sections          | Must be labelled; avoid "navigation" in the label (screen readers announce this) |
-| `main`    | Primary content              | Only one per page; must contain the primary `<h1>`                               |
-| `aside`   | Tangentially related content | Content removable without changing the page's main story (sidebars, ads)         |
-| `search`  | Search functionality         | Contains the search form, not the results                                        |
-| `form`    | User input                   | Only becomes a landmark when labelled via `aria-labelledby` or `aria-label`      |
-| `article` | Self-contained content       | Would make sense syndicated or standalone                                        |
-| `section` | Thematic grouping            | Only becomes a landmark when labelled                                            |
+| Element   | Use When                     | Notes                                                                                                                                                                                                       |
+| --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `header`  | Page or section header       | Can appear multiple times in different contexts                                                                                                                                                             |
+| `footer`  | Page or section footer       | Contact info, copyright, related links                                                                                                                                                                      |
+| `nav`     | Navigation sections          | One may be unnamed; give multiple landmarks names that distinguish their purpose. Identical repeated navigation may share a name. Avoid "navigation" in the label because screen readers announce the role. |
+| `main`    | Primary content              | Only one per page; must contain the primary `<h1>`                                                                                                                                                          |
+| `aside`   | Tangentially related content | Content removable without changing the page's main story (sidebars, ads)                                                                                                                                    |
+| `search`  | Search functionality         | Contains the search form, not the results                                                                                                                                                                   |
+| `form`    | User input                   | Only becomes a landmark when labelled via `aria-labelledby` or `aria-label`                                                                                                                                 |
+| `article` | Self-contained content       | Would make sense syndicated or standalone                                                                                                                                                                   |
+| `section` | Thematic grouping            | Only becomes a landmark when labelled                                                                                                                                                                       |
 
 #### `<main>` must contain the primary `<h1>`
 
@@ -251,27 +251,27 @@ Sometimes text looks like a heading but shouldn't be one semantically. Use CSS c
 
 ### When to Use Lists
 
-Lists are most useful when **knowing the number of items helps the user**:
+Use a list when sibling items have a semantic relationship that should remain clear without visual styling:
 
-- Navigation menus (how many options?)
-- Search results (how many matches?)
-- Image galleries (how many images?)
+- Navigation menus
+- Search results
+- Image galleries
 - Steps in a process
 
 **Questions to ask:**
 
 - Are these items genuinely peers?
-- Would removing one make the others feel incomplete?
-- Is there an implicit "here are N things" being communicated?
+- Does the order or ranking carry meaning?
+- Are these term-description pairs rather than peer items?
 
 ### List Types
 
-| Type   | Use When                                 | Example                               |
-| ------ | ---------------------------------------- | ------------------------------------- |
-| `ul`   | Unordered collection where count matters | Nav items, search results             |
-| `ol`   | Sequential steps or ranked items         | Recipes, instructions, top-10 lists   |
-| `dl`   | Term-description pairs                   | Glossaries, metadata, key-value pairs |
-| `menu` | Toolbar commands                         | Action buttons, not navigation        |
+| Type   | Use When                                       | Example                               |
+| ------ | ---------------------------------------------- | ------------------------------------- |
+| `ul`   | Related peer items without meaningful sequence | Nav items, search results             |
+| `ol`   | Items whose sequence or ranking matters        | Recipes, instructions, top-10 lists   |
+| `dl`   | Term-description pairs                         | Glossaries, metadata, key-value pairs |
+| `menu` | Toolbar commands                               | Action buttons, not navigation        |
 
 **Ordered list attributes:** Use `reversed` for countdown-style lists (e.g., a top 10 listed from 10 to 1). Use `start` to begin numbering from a specific value. Both are native HTML—no JavaScript required.
 
@@ -287,7 +287,7 @@ Note: A single `dt` can have multiple `dd` elements for multiple related descrip
 
 ### Decorative List Separators
 
-When using CSS `::before` or `::after` to inject visual separators (e.g., breadcrumb `›`), browsers automatically exclude generated content from the accessibility tree—no extra markup is required. Do **not** try to hide it with `aria-hidden: "true"` as a CSS property; that is invalid and has no effect. If injecting separators via HTML (not CSS), use `<span aria-hidden="true">` on the HTML element.
+Keep visual separators decorative. Prefer borders or other non-content styling because CSS-generated `::before` and `::after` content can be exposed inconsistently across browser and assistive-technology combinations. If generated content is necessary, test the supported combinations. Do **not** try to hide it with `aria-hidden: "true"` as a CSS property; that is invalid and has no effect. If injecting separators via HTML, use `<span aria-hidden="true">` on the element.
 
 ## Interactive Elements
 
@@ -410,20 +410,22 @@ Legends can be visually hidden while still providing accessible names.
 ```html
 <!-- Correct: all filter controls share a single search landmark -->
 <search aria-label="Filter employees">
-  <label for="q">Search</label>
-  <input type="search" id="q" name="q" />
-
-  <label for="dept">Department</label>
-  <select id="dept" name="dept">
-    ...
-  </select>
-
-  <label for="status">Status</label>
-  <select id="status" name="status">
-    ...
-  </select>
-
-  <button type="submit">Apply filters</button>
+  <form action="/employees" method="get">
+    <label for="q">Search</label>
+    <input type="search" id="q" name="q" />
+
+    <label for="dept">Department</label>
+    <select id="dept" name="dept">
+      ...
+    </select>
+
+    <label for="status">Status</label>
+    <select id="status" name="status">
+      ...
+    </select>
+
+    <button type="submit">Apply filters</button>
+  </form>
 </search>
 
 <!-- Wrong: only the text input is wrapped -->
@@ -531,7 +533,7 @@ In order of preference:
 2. **Horizontal scroll** — Preserves semantics but may challenge users with motor difficulties
 3. **Component duplication (cards on mobile)** — Last resort; maintain accessibility in both versions
 
-Note: Modern browsers (including Safari) no longer strip table semantics when applying `display: grid` or `display: flex`, opening new responsive possibilities.
+Keep the table's native display and put overflow on a wrapper. Changing table elements to `display: grid` or `display: flex` can remove native table semantics in some browser and assistive-technology combinations; rely on altered display semantics only after testing every supported combination.
 
 ## Code Review Checklist