css-is-awesome 1.8.1 → 1.9.0

package/AGENTS.md

@@ -26,7 +26,12 @@ When asked to add a UI element, follow this order:
 4. **All values come from tokens.** Never hardcode `#3A5FCD`, `1rem`, `8px`. Use `cia.color(primary)`, `cia.space(4)`, `cia.radius(md)`.
 5. **No BEM.** No `__element` / `--modifier` chains. `cia-` is a single-class namespace prefix, not BEM.
 6. **No JavaScript.** Cia ships zero JS in the npm package. The 6 interactive components (accordion, modal, tooltip, dropdown, tabs, copy-button) use native HTML primitives — `<details name>`, `<dialog>`, `[popover]`, radio + `:has()`. Mobile navigation follows the same doctrine: the `hamburger` / `drawer` / `sheet` / `dock` mixin family rides `[popover]` + CSS Grid — see the `mobile-nav` recipe (hamburger + drawer) and the `bottom-nav` recipe (dock + sheets). **This rule binds cia, not you.** If you're *consuming* cia (building an app/component library on top of it), write JavaScript/framework components freely — React, SVG charts, interactivity, all of it — and use cia purely for styling (mixins + tokens). Compose the mixins to build any visual you want; you are not limited to cia's pre-made component mixins.
-7. **Pages stack by named grid areas — the layout mixins own the shell.** Every page's structure is declared once as `grid-template-areas` (`"navbar" "hero" … "footer"`), and each section claims its slot with `grid-area`. Never hand-write that: use `cia.page-layout(default | sidebar-left | sidebar-right | holy-grail)` for a full viewport shell (100dvh, sticky footer, auto mobile collapse), `cia.layout((sidebar content toc), $tracks: …)` for custom rows of regions, and `cia.page-header` / `cia.page-main` / `cia.page-footer` / `cia.area(name)` for the children. Named areas are the single source of truth for stacking — mobile is just a different `grid-template-areas`, not a pile of margin overrides. Baseline since 2020.
+7. **Grid is the skeleton; Flex is the quick moves.** Three levels, strictly:
+   - **The page shell is CSS Grid with landmark-named areas.** The body's areas ARE the document's landmarks — `nav`, `main`, `footer` — so the area map reads like the page and screen readers get the structure for free. Declared once via `cia.page-layout(default | sidebar-left | sidebar-right | holy-grail)` (100dvh, sticky footer, auto mobile collapse) or `cia.layout((sidebar content toc), $tracks: …)`; children claim slots with `cia.page-header` / `cia.page-main` / `cia.page-footer` / `cia.area(name)`. Baseline since 2020.
+   - **The doctrine scales inward: any control-dense region gets its own named-area grid.** A docs article (`header / demo / usage / tabs / footer`), a selections rail (`filter / list`), a dashboard — when a region has many controls, name its rows with `cia.layout(...)` too. Nested grids all the way down where density warrants; the grid's `gap` is the region's entire vertical rhythm (children carry no rhythm margins).
+   - **Flex lives at the leaves** — simple rows and columns you flip with one command: `@include cia.flex($direction: column)` turns a row into a stack. Flex arranges the contents of a slot the grid gave it; it never builds the page.
+
+   Mobile is just a different `grid-template-areas` map — restack, hide (with `display: none`; omitting an area does not hide its element), reorder — never a pile of margin overrides. Never hand-write `grid-template-areas`; the layout mixins own it.
 8. **On phones, things take the space they're in.** Below the mobile breakpoint an interactive surface fills its *container* — 100% of the column it lives in, inside the page's existing padding and formatting (never edge-to-edge past the page's gutters, never a floating mid-width popup). Triggers stretch to 100% with `justify-content: space-between` (label left, affordance right). A top-layer popover menu can't size to its container directly, so match its trigger via CSS anchor positioning (`anchor-name` on the trigger; `inset-inline: anchor(start) anchor(end)` under `@supports (anchor-name: --a)`) — opening directly under the trigger, with `position-try-fallbacks: flip-block` so it flips above when it would run off the bottom of the screen — with viewport-minus-gutters as the no-anchor fallback — and set it at `&[popover]` specificity, since the dropdown mixin's `inset: unset` reset otherwise wins. Also set `width: auto`: the UA's `[popover] { width: fit-content }` otherwise beats both inset edges and the menu hugs its content. `cia.sheet`, `cia.drawer($side: top|bottom)` and `cia.dock` already obey the rule. **Deliberate exception — code blocks:** on phones, code is allowed to run off into a horizontal scroll *inside its own box* (`white-space: pre; overflow-x: auto`) — never wrap, shrink, or reflow code to fit, and never let it widen the page; the copy button carries usability for long lines.
 9. **Style semantic state off ARIA, not a parallel `data-*`.** When a state has an ARIA source of truth, hook your styles to *that* attribute: `[aria-selected="true"]`, `[aria-expanded="true"]`, `[aria-invalid="true"]`, `:disabled, [aria-disabled="true"]`, `[aria-pressed="true"]`, `[aria-checked="true"]`, `[aria-current]`, `[role="tab"]`. Then the state can't be styled without setting the ARIA a screen reader needs — **accessible-by-construction**, one source of truth for looks + a11y. Reserve `data-*` for **cosmetic-only** variants (`data-size`, `data-variant`, `data-color`) that carry no ARIA meaning. cia's own components already do this where native HTML doesn't cover it (`[aria-current="page"]`, `[aria-selected="true"]`, `[role="option"]`).
 

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+# [1.9.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.8.2...v1.9.0) (2026-09-05)
+
+
+### Features
+
+* **cli:** cia add (recipe registry) + cia analyze (design-system health) ([194c253](https://github.com/Jerry2d3d/css-is-awesome/commit/194c253a35eec68c68e2f2ca7402fd4e72a4d6ad))
+* **site:** /docs/browser-support - the dated two-tier support matrix ([d2e4604](https://github.com/Jerry2d3d/css-is-awesome/commit/d2e4604c6a331b467bdcd71b30ba2b7f7fe90f68))
+
+## [1.8.2](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.8.1...v1.8.2) (2026-09-05)
+
+
+### Bug Fixes
+
+* **site:** ComponentDoc must be a client component ([fd6ab31](https://github.com/Jerry2d3d/css-is-awesome/commit/fd6ab3117fb06d37c9ee1da4d1071324cae87338))
+* **tabs:** tab list is a <nav> - the div list shifted every panel index ([5099145](https://github.com/Jerry2d3d/css-is-awesome/commit/50991455c0646ffa7ec468166d29d239cbc4c235)), closes [#1](https://github.com/Jerry2d3d/css-is-awesome/issues/1)
+
+
+### Features
+
+* **site:** component docs are data - DocEntry registry + article grid (phase 3) ([98d2419](https://github.com/Jerry2d3d/css-is-awesome/commit/98d2419af9b543a6d09888d54a4f1d4b1ca757f6))
+* **site:** docs rail anatomy (Boiler handoff, phases 1+2) + the full layout doctrine written down ([fa1fa8b](https://github.com/Jerry2d3d/css-is-awesome/commit/fa1fa8b4e182793f1806d4e13af051394ad7cf8b)), closes [#7](https://github.com/Jerry2d3d/css-is-awesome/issues/7)
+
 ## [1.8.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.8.0...v1.8.1) (2026-09-04)
 
 

package/README.md

@@ -204,6 +204,8 @@ cia ships **no component library** — deliberately. Interactive patterns arrive
 
 **Shipped:** `dialog`, `combobox`, `print-to-pdf`, `mobile-nav`, `bottom-nav`. Queued next: `datepicker`, `data-table`, `command-palette`.
 
+**Layout doctrine: Grid is the skeleton, Flex is the quick moves.** The page shell is CSS Grid with landmark-named areas (`nav / main / footer` — the map reads like the page); any control-dense region inside gets its own named-area grid whose `gap` carries all vertical rhythm; flex lives at the leaves for one-command flips (`cia.flex($direction: column)`). `cia.page-layout()` and `cia.layout()` own the maps — mobile is a different area map, never margin overrides.
+
 **Mobile navigation is system API, not an exercise for the reader.** Four mixins — `cia.hamburger`, `cia.drawer`, `cia.sheet`, `cia.dock` — cover both phone layouts: the **flex layout** (one fluid nav/main/footer shell that reshapes with the screen, hamburger opening a slide-in drawer — recipe [`mobile-nav`](./scss/recipes/mobile-nav.md)) and the **app layout** (a fixed bottom dock whose slots open slide-up sheets — recipe [`bottom-nav`](./scss/recipes/bottom-nav.md)). Zero JavaScript: everything rides CSS Grid and the native Popover API — the browser owns open state, `aria-expanded`, Esc and light dismiss. The docs site dogfoods the app layout on phones. The same doctrine extends to dropdowns: on phones an interactive surface takes the space it's in, so a `cia.dropdown` menu opens 1px under its full-width trigger at the trigger's exact width — CSS anchor positioning, flipping above when the screen bottom would clip it. The full spec is the [mobile playbook](https://cssisawesome.com/docs/mobile/).
 
 Humans read them at [`/docs/recipes`](https://cssisawesome.com/docs/recipes/); AI agents pull them over MCP with `list_recipes` / `get_recipe`.
@@ -219,6 +221,17 @@ npx cia migrate bootstrap ./scss/_variables.scss
 
 Both accept `--help` for the full option list. Prose walkthroughs live at [`/docs/migration-tailwind`](https://cssisawesome.com/docs/migration-tailwind/) and [`/docs/migration-bootstrap`](https://cssisawesome.com/docs/migration-bootstrap/).
 
+The CLI also carries the registry and the health check:
+
+```bash
+npx cia add --list          # browse the recipe book
+npx cia add bottom-nav      # copy a recipe into your project — you own the pattern
+npx cia analyze src/styles  # design-system health: dead cia.* symbols, the
+                            # space() scale trap, hard-coded colors, BEM creep
+```
+
+`cia analyze` reads the real API surface from the installed package and exits non-zero on errors, so it slots straight into CI.
+
 ## Print / PDF (zero JS)
 
 Print support is a pure-CSS layer — the browser's native **Print → Save as PDF** is the generator, and cia ships no JavaScript for it:

package/bin/add-recipe.cjs

@@ -0,0 +1,94 @@
+/**
+ * cia add — copy a recipe from the installed package into the project.
+ *
+ * The recipes book ships inside the npm package (scss/recipes/*.md). This
+ * command copies one into the consumer's tree so they OWN the pattern —
+ * the registry model: own the generated code, don't import an opaque
+ * component. Markdown pattern recipes only; the opt-in SCSS recipes
+ * (e.g. bare-tags) are `@use`d, not copied.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const RECIPES_DIR = path.join(__dirname, '..', 'scss', 'recipes');
+
+const HELP = `cia add — copy a recipe into your project
+
+Usage:
+  cia add <recipe> [options]
+  cia add --list
+
+Options:
+  --list           List available recipes.
+  --out <path>     Output path. Default: ./cia-recipes/<recipe>.md
+  --force          Overwrite if the target file exists.
+
+Examples:
+  cia add --list
+  cia add bottom-nav
+  cia add mobile-nav --out docs/patterns/mobile-nav.md
+`;
+
+function fail(message) {
+  process.stderr.write(`cia add: ${message}\n`);
+  process.exit(1);
+}
+
+function listRecipes() {
+  return fs
+    .readdirSync(RECIPES_DIR)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('_') && f !== 'README.md')
+    .map((f) => f.replace(/\.md$/, ''))
+    .sort();
+}
+
+function frontmatterDescription(raw) {
+  const m = raw.match(/^---[\s\S]*?\ndescription:\s*(.+?)\r?\n[\s\S]*?---/);
+  return m ? m[1].trim() : '';
+}
+
+async function run(args) {
+  if (!args.length || args[0] === '-h' || args[0] === '--help' || args[0] === 'help') {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  if (args.includes('--list')) {
+    for (const slug of listRecipes()) {
+      const raw = fs.readFileSync(path.join(RECIPES_DIR, `${slug}.md`), 'utf8');
+      process.stdout.write(`${slug.padEnd(16)} ${frontmatterDescription(raw)}\n`);
+    }
+    return;
+  }
+
+  const slug = args[0];
+  const recipes = listRecipes();
+  if (!recipes.includes(slug)) {
+    fail(`unknown recipe '${slug}'. Available: ${recipes.join(', ')}.`);
+  }
+
+  const outFlag = args.indexOf('--out');
+  const outPath =
+    outFlag !== -1 && args[outFlag + 1]
+      ? path.resolve(args[outFlag + 1])
+      : path.resolve('cia-recipes', `${slug}.md`);
+
+  if (fs.existsSync(outPath) && !args.includes('--force')) {
+    fail(`${path.relative(process.cwd(), outPath)} already exists. Pass --force to overwrite.`);
+  }
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.copyFileSync(path.join(RECIPES_DIR, `${slug}.md`), outPath);
+
+  const rel = path.relative(process.cwd(), outPath);
+  process.stdout.write(
+    `✓ ${slug} → ${rel}\n\n` +
+      `The recipe is yours now — correct HTML, the cia mixin calls, and the\n` +
+      `a11y checklist. Read it, copy the pattern into your stack, keep the\n` +
+      `checklist. Docs: https://cssisawesome.com/docs/recipes/${slug}/\n`,
+  );
+}
+
+module.exports = { run };

package/bin/analyze.cjs

@@ -0,0 +1,191 @@
+/**
+ * cia analyze — design-system health check for a consumer project.
+ *
+ * Reads the REAL API surface from the installed package's SCSS sources
+ * (the same files the MCP server serves), then audits the project's
+ * stylesheets for:
+ *   - cia.* calls that don't resolve (dead symbols — typos, removals)
+ *   - the space() scale trap (numbered scale is 1–9; unknown keys pass
+ *     through raw and silently invalidate the declaration)
+ *   - hard-coded hex colors (values should come from tokens)
+ *   - BEM-style class names (__ / -- chains are forbidden in cia projects)
+ *   - hand-written grid-template-areas (the layout mixins own the maps)
+ *
+ * Zero dependencies, filesystem only — same philosophy as the MCP server.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PKG_SCSS = path.join(__dirname, '..', 'scss');
+
+const HELP = `cia analyze — design-system health check
+
+Usage:
+  cia analyze [path] [options]
+
+Scans [path] (default: current directory) for *.scss files and audits
+them against the installed css-is-awesome API.
+
+Options:
+  --namespace <ns>   Extra namespace(s) to treat as cia (comma-separated).
+                     Auto-detected per file from @use lines; use this when
+                     imports are aliased through an intermediate file.
+  --json             Machine-readable report on stdout.
+  --strict           Exit 1 on warnings too (default: errors only).
+
+Examples:
+  cia analyze
+  cia analyze src/styles --json
+  cia analyze src --namespace m,l
+`;
+
+// ── API surface discovery ───────────────────────────────────────────────────
+
+function collectSymbols() {
+  const symbols = new Set();
+  const files = [];
+  const top = ['_mixins.scss', '_layout.scss', '_animations.scss', '_generator.scss'];
+  for (const f of top) files.push(path.join(PKG_SCSS, f));
+  const compDir = path.join(PKG_SCSS, 'components');
+  for (const f of fs.readdirSync(compDir)) {
+    if (f.endsWith('.scss')) files.push(path.join(compDir, f));
+  }
+  for (const file of files) {
+    let src = '';
+    try {
+      src = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const m of src.matchAll(/@(?:mixin|function)\s+([a-zA-Z][\w-]*)/g)) {
+      if (!m[1].startsWith('_')) symbols.add(m[1]);
+    }
+  }
+  // Icon mixins are forwarded with an icon- prefix by the /api barrel.
+  const icons = path.join(PKG_SCSS, '_icons.scss');
+  try {
+    const src = fs.readFileSync(icons, 'utf8');
+    for (const m of src.matchAll(/@(?:mixin|function)\s+([a-zA-Z][\w-]*)/g)) {
+      if (!m[1].startsWith('_')) symbols.add(`icon-${m[1]}`);
+    }
+  } catch {
+    /* icons module optional */
+  }
+  return symbols;
+}
+
+// ── project scan ────────────────────────────────────────────────────────────
+
+function walkScss(dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkScss(full, out);
+    else if (entry.name.endsWith('.scss')) out.push(full);
+  }
+  return out;
+}
+
+const CIA_SOURCE = /^(?:css-is-awesome(?:\/|$)|pkg:css-is-awesome|api$|mixins$|layout$|animations$|generator$|icons$|components(?:\/|$))/;
+
+function detectNamespaces(src, extra) {
+  const ns = new Set(extra);
+  for (const m of src.matchAll(/@use\s+['"]([^'"]+)['"]\s+as\s+([a-zA-Z][\w-]*)/g)) {
+    if (CIA_SOURCE.test(m[1])) ns.add(m[2]);
+  }
+  // `@use 'css-is-awesome/api';` without `as` → namespace is the last segment.
+  for (const m of src.matchAll(/@use\s+['"]([^'"]+)['"]\s*;/g)) {
+    if (CIA_SOURCE.test(m[1])) ns.add(m[1].split('/').pop().replace(/\.scss$/, ''));
+  }
+  return ns;
+}
+
+function stripComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+}
+
+function analyzeFile(file, symbols, extraNs) {
+  const raw = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
+  const src = stripComments(raw);
+  const ns = detectNamespaces(src, extraNs);
+  const findings = [];
+  if (ns.size) {
+    const nsPattern = [...ns].map((n) => n.replace(/[-]/g, '\\-')).join('|');
+    const callRe = new RegExp(`\\b(?:${nsPattern})\\.([a-zA-Z][\\w-]*)`, 'g');
+    for (const m of src.matchAll(callRe)) {
+      const sym = m[1];
+      if (!symbols.has(sym)) {
+        findings.push({ level: 'error', rule: 'unknown-symbol', detail: `cia.${sym} does not exist in the installed API` });
+      }
+    }
+    // space() scale trap: numbered keys are 1–9; higher/fractional numbers
+    // pass through raw and silently invalidate the declaration.
+    const spaceRe = new RegExp(`\\b(?:${nsPattern})\\.space\\(\\s*(\\d+(?:\\.\\d+)?)\\s*\\)`, 'g');
+    for (const m of src.matchAll(spaceRe)) {
+      const n = Number(m[1]);
+      if (!Number.isInteger(n) || n > 9) {
+        findings.push({ level: 'error', rule: 'space-scale', detail: `space(${m[1]}) — the numbered scale is 1–9; this emits a unitless number and the browser drops the declaration. Use grid(n) for 4px multiples or pass an explicit unit.` });
+      }
+    }
+  }
+  for (const m of src.matchAll(/#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g)) {
+    findings.push({ level: 'warn', rule: 'hard-coded-color', detail: `${m[0]} — values should come from tokens (cia.color(...) / var(--...))` });
+  }
+  for (const m of src.matchAll(/\.[a-zA-Z][\w]*(?:__|--)[\w-]+/g)) {
+    findings.push({ level: 'warn', rule: 'bem', detail: `${m[0]} — BEM chains are forbidden; use semantic single-class names` });
+  }
+  if (/(?:^|[{;\s])grid-template-areas\s*:/m.test(src)) {
+    findings.push({ level: 'info', rule: 'hand-written-areas', detail: 'grid-template-areas written by hand — the layout mixins (page-layout / layout / area) own the maps' });
+  }
+  return { file, namespaces: [...ns], findings };
+}
+
+// ── report ──────────────────────────────────────────────────────────────────
+
+async function run(args) {
+  if (args[0] === '-h' || args[0] === '--help' || args[0] === 'help') {
+    process.stdout.write(HELP);
+    return;
+  }
+  const json = args.includes('--json');
+  const strict = args.includes('--strict');
+  const nsFlag = args.indexOf('--namespace');
+  const extraNs = nsFlag !== -1 && args[nsFlag + 1] ? args[nsFlag + 1].split(',') : [];
+  const target = path.resolve(args.find((a) => !a.startsWith('--') && a !== extraNs.join(',')) || '.');
+
+  if (!fs.existsSync(target)) {
+    process.stderr.write(`cia analyze: path not found: ${target}\n`);
+    process.exit(1);
+  }
+
+  const symbols = collectSymbols();
+  const files = walkScss(target);
+  const results = files.map((f) => analyzeFile(f, symbols, extraNs)).filter((r) => r.findings.length || r.namespaces.length);
+
+  const counts = { error: 0, warn: 0, info: 0 };
+  for (const r of results) for (const f of r.findings) counts[f.level]++;
+  const ciaFiles = results.filter((r) => r.namespaces.length).length;
+  const health = Math.max(0, 100 - counts.error * 10 - counts.warn * 2 - counts.info);
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ target, files: files.length, ciaFiles, apiSymbols: symbols.size, counts, health, results }, null, 2) + '\n');
+  } else {
+    process.stdout.write(`\ncia analyze — ${path.relative(process.cwd(), target) || '.'}\n`);
+    process.stdout.write(`${files.length} scss file(s), ${ciaFiles} using cia, ${symbols.size} API symbols known\n\n`);
+    for (const r of results) {
+      if (!r.findings.length) continue;
+      process.stdout.write(`${path.relative(process.cwd(), r.file)}\n`);
+      for (const f of r.findings) {
+        const mark = f.level === 'error' ? '✗' : f.level === 'warn' ? '⚠' : 'ℹ';
+        process.stdout.write(`  ${mark} [${f.rule}] ${f.detail}\n`);
+      }
+    }
+    process.stdout.write(`\nDesign-system health: ${health}%  (${counts.error} error, ${counts.warn} warn, ${counts.info} info)\n`);
+  }
+
+  if (counts.error > 0 || (strict && counts.warn > 0)) process.exit(1);
+}
+
+module.exports = { run };

package/bin/cia.cjs

@@ -27,11 +27,17 @@ Usage:
 
 Commands:
   migrate <tool> [path]   Convert another design system's config to a cia
-                          theme. Tools: tailwind | bootstrap (planned).
+                          theme. Tools: tailwind | bootstrap.
+  add <recipe>            Copy a recipe from the book into your project
+                          (own the pattern). \`cia add --list\` to browse.
+  analyze [path]          Design-system health check: dead cia.* symbols,
+                          the space() scale trap, hard-coded colors, BEM,
+                          hand-written area maps.
 
 Examples:
   cia migrate tailwind ./tailwind.config.js
-  cia migrate tailwind                       # auto-detect tailwind.config.*
+  cia add bottom-nav
+  cia analyze src/styles
 
 Run \`cia <command> --help\` for command-specific help.
 `;
@@ -106,6 +112,18 @@ async function main() {
     fail(`unknown migrate tool '${tool}'. Available: tailwind, bootstrap.`);
   }
 
+  if (command === 'add') {
+    const { run } = require('./add-recipe.cjs');
+    await run(rest);
+    return;
+  }
+
+  if (command === 'analyze') {
+    const { run } = require('./analyze.cjs');
+    await run(rest);
+    return;
+  }
+
   fail(`unknown command '${command}'. Run \`cia --help\` for usage.`);
 }
 

package/dist/tokens.d.ts

@@ -1,4 +1,4 @@
-// Generated from scripts/theme-contract.json on 2026-09-04.
+// Generated from scripts/theme-contract.json on 2026-09-05.
 // Do not edit by hand. Run `npm run build:token-types` to regenerate.
 
 /** Every CSS custom property cia themes are required to declare. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "A token-driven SCSS design system with light/dark theming, semantic color tokens, and a 800+ LOC mixin API.",
   "homepage": "https://github.com/Jerry2d3d/css-is-awesome#readme",
   "bugs": {

package/scss/components/_tabs.scss

@@ -8,14 +8,22 @@
 //   <div class="cia-tabs">
 //     <input type="radio" name="t" id="t1" checked>
 //     <input type="radio" name="t" id="t2">
-//     <div class="cia-tab-list" role="tablist">
+//     <nav class="cia-tab-list" role="tablist">
 //       <label for="t1" role="tab">Tab 1</label>
 //       <label for="t2" role="tab">Tab 2</label>
-//     </div>
+//     </nav>
 //     <div class="cia-tab-panel" role="tabpanel">Content 1</div>
 //     <div class="cia-tab-panel" role="tabpanel">Content 2</div>
 //   </div>
 //
+// ⚠️ CONTRACT: the tab list must NOT share the panels' element type.
+// Panel switching indexes panels with :nth-of-type(), which counts by
+// ELEMENT TYPE among siblings — a <div> tab list would be div #1, every
+// panel's index would shift by one, and tab 1 would show no panel while
+// the labels still highlighted correctly (we shipped exactly that; fixed
+// 2026-09-04 by making the documented list a <nav>). CSS has no
+// nth-of-class, so the markup carries this rule instead of the selector.
+//
 // A11y baseline: keyboard nav (Tab + arrows + Space) and screen-reader text
 // are native. For full aria-selected sync ship the tiny opt-in JS shim
 // documented at /docs/components/tabs#aria.