@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/components/anchor/anchor.stories.js

@@ -55,7 +55,7 @@ prin \`ResizeObserver\` — fără a fi necesară setarea manuală a \`max-width
 
   <bd-button-link
     slot="cta"
-    kind="danger"
+    variant="accent"
     size="md"
     href="https://www.bitdefender.com/buy"
     label="Cumpără acum"
@@ -111,6 +111,18 @@ nu-i o valoare universală, depinde de conținutul acelui header.
 ### Slot \`cta\`
 Orice element cu \`slot="cta"\` înlocuiește butonul CTA fallback.
 Pe mobile devine automat full-width prin \`::slotted([slot="cta"])\`.
+
+---
+
+### Accesibilitate
+Este **navigație**, nu un set de tab-uri: linkurile duc la secțiuni care există
+deja în pagină. De aceea folosește \`<nav>\` + linkuri + \`aria-current="true"\`
+pe cel activ — nu \`role="tablist"\` / \`aria-selected\`, care înseamnă
+"panoul afișat acum". Pentru un strip de tab-uri reale vezi **Components/Tab List**.
+
+Pe mobile, lista devine un **disclosure** (APG Disclosure Navigation Menu):
+butonul poartă \`aria-expanded\` + \`aria-controls\`, iar panoul conține un
+\`<ul>\` de linkuri reale. \`Escape\` închide panoul și readuce focusul pe buton.
         `
       }
     }
@@ -161,12 +173,11 @@ const renderWithSlotCta = (labels, ctaLabel = "Cumpără acum", ctaHref = "#sect
     ${navItems(labels)}
     <bd-button-link
       slot="cta"
-      kind="danger"
+      variant="accent"
       size="md"
       href=${ctaHref}
       label=${ctaLabel}
-      font-size="16px"
-      font-weight="600"
+      font-size="base"
       buyLink
     >${ctaLabel}</bd-button-link>
   </bd-anchor-nav>
@@ -193,7 +204,7 @@ const withSiblingContent = (navTemplate) => html`
       border-radius: 8px;
       text-align: center;
       color: #1e40af;
-      font-family: sans-serif;
+      font-family: var(--typography-fontFamily-sans);
     ">
       <strong>Sibling content — 900px max-width</strong><br>
       <span style="font-size: 0.875rem; opacity: 0.8;">
@@ -237,12 +248,11 @@ export const WithSlotCtaOutline = {
       ${navItems(["Overview", "Features", "Pricing"])}
       <bd-button-link
         slot="cta"
-        kind="outline"
+        variant="ghost"
         size="md"
         href="https://www.bitdefender.com/buy"
         label="Cumpără acum"
-        font-size="16px"
-        font-weight="600"
+        font-size="base"
       >Cumpără acum</bd-button-link>
     </bd-anchor-nav>
   `,
@@ -383,7 +393,7 @@ export const WithScrollTargets = {
           background: #EDF9FF; border-bottom: 1px solid #e2e8f0;
         ">
           <bd-h as="h2">Overview Section</bd-h>
-          <bd-p kind="regular">
+          <bd-p variant="regular">
             Navul de mai sus se aliniază automat la lățimea acestui container (800px).
             Scroll în jos pentru a vedea sticky și scroll spy în acțiune.
           </bd-p>
@@ -394,7 +404,7 @@ export const WithScrollTargets = {
           background: #fff; border-bottom: 1px solid #e2e8f0;
         ">
           <bd-h as="h2">Features Section</bd-h>
-          <bd-p kind="regular">Conținut Features. Link-ul din nav devine activ când ajungi aici.</bd-p>
+          <bd-p variant="regular">Conținut Features. Link-ul din nav devine activ când ajungi aici.</bd-p>
         </div>
 
         <div id="anchor-3-section" style="
@@ -402,14 +412,14 @@ export const WithScrollTargets = {
           background: #EDF9FF; border-bottom: 1px solid #e2e8f0;
         ">
           <bd-h as="h2">Pricing Section</bd-h>
-          <bd-p kind="regular">Conținut Pricing.</bd-p>
+          <bd-p variant="regular">Conținut Pricing.</bd-p>
         </div>
 
         <div id="section-pricing" style="
           min-height: 40vh; padding: 80px 24px; background: #fff;
         ">
           <bd-h as="h2">Buy Now Target</bd-h>
-          <bd-p kind="regular">Butonul CTA scrollează până aici.</bd-p>
+          <bd-p variant="regular">Butonul CTA scrollează până aici.</bd-p>
         </div>
 
       </div>

package/src/components/annotation/annotation.css.js

@@ -0,0 +1,58 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const annotationCSS = css`
+  :host { display: inline; }
+
+  .footnote {
+    font-size: var(--footnote-reference-fontSize);
+    font-weight: var(--footnote-reference-fontWeight);
+    line-height: var(--footnote-reference-lineHeight);
+    vertical-align: var(--footnote-reference-verticalAlign);
+    color: var(--footnote-reference-color);
+    margin-left: var(--footnote-reference-marginLeft);
+    margin-right: var(--footnote-reference-marginRight);
+    text-decoration: none;
+  }
+
+  .citation {
+    font-size: var(--citation-reference-fontSize);
+    font-weight: var(--citation-reference-fontWeight);
+    line-height: var(--citation-reference-lineHeight);
+    color: var(--citation-reference-color);
+    text-decoration: var(--citation-reference-textDecoration);
+  }
+
+  .citation:hover {
+    color: var(--citation-reference-hover-color);
+    text-decoration: var(--citation-reference-hover-textDecoration);
+  }
+
+  .citation:focus-visible,
+  .footnote:focus-visible {
+    /* the one focus ring — see Foundations/Focus. A two-colour ring whose
+       white inner band keeps it visible on a coloured or dark surface, which
+       a single-colour outline cannot do. */
+    outline: none;
+    box-shadow: var(--focus-outline-primary);
+    border-radius: var(--focus-outline-radius);
+  }
+
+  .sup {
+    font-size: var(--math-superscript-fontSize);
+    font-weight: var(--math-superscript-fontWeight);
+    line-height: var(--math-superscript-lineHeight);
+    vertical-align: var(--math-superscript-verticalAlign);
+    margin-left: var(--math-superscript-marginLeft);
+  }
+
+  .sub {
+    font-size: var(--math-subscript-fontSize);
+    font-weight: var(--math-subscript-fontWeight);
+    line-height: var(--math-subscript-lineHeight);
+    vertical-align: var(--math-subscript-verticalAlign);
+    margin-left: var(--math-subscript-marginLeft);
+  }
+`;
+
+export default annotationCSS;

package/src/components/annotation/annotation.js

@@ -0,0 +1,67 @@
+import { LitElement, html, nothing } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { annotationCSS } from './annotation.css.js';
+
+export class BdFootnote extends LitElement {
+  static styles = [annotationCSS];
+
+  static properties = {
+    href: { type: String }
+  };
+
+  constructor() {
+    super();
+    this.href = '';
+  }
+
+  render() {
+    return html`
+      <a class="footnote" href=${this.href || nothing}><slot></slot></a>
+    `;
+  }
+}
+
+export class BdCitation extends LitElement {
+  static styles = [annotationCSS];
+
+  static properties = {
+    href: { type: String }
+  };
+
+  constructor() {
+    super();
+    this.href = '';
+  }
+
+  render() {
+    return html`
+      <a class="citation" href=${this.href || nothing}><slot></slot></a>
+    `;
+  }
+}
+
+export class BdSup extends LitElement {
+  static styles = [annotationCSS];
+
+  render() {
+    return html`
+      <sup class="sup"><slot></slot></sup>
+    `;
+  }
+}
+
+export class BdSub extends LitElement {
+  static styles = [annotationCSS];
+
+  render() {
+    return html`
+      <sub class="sub"><slot></slot></sub>
+    `;
+  }
+}
+
+customElements.define('bd-footnote', BdFootnote);
+customElements.define('bd-citation', BdCitation);
+customElements.define('bd-sup', BdSup);
+customElements.define('bd-sub', BdSub);

package/src/components/annotation/annotation.stories.js

@@ -0,0 +1,63 @@
+import { html } from 'lit';
+import './annotation.js';
+
+export default {
+  title     : 'Atoms/Annotation',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+Four small elements for references and maths inside prose.
+
+- \`<bd-footnote>\` — a superscript reference marker, optionally linked
+- \`<bd-citation>\` — a source reference, optionally linked
+- \`<bd-sup>\` / \`<bd-sub>\` — superscript and subscript that do **not** disturb
+  the line box
+
+### Usage
+\`\`\`html
+Detections rose sharply<bd-footnote href="#n1">1</bd-footnote> last quarter.
+
+<bd-citation href="https://example.com/report">Threat Landscape 2026</bd-citation>
+
+The formula is CO<bd-sub>2</bd-sub> and the unit is m<bd-sup>3</bd-sup>.
+\`\`\`
+
+### Props
+| Prop | Applies to | Default |
+|---|---|---|
+| \`href\` | \`bd-footnote\` and \`bd-citation\`. Omit to render unlinked. | \`''\` |
+
+\`bd-sup\` and \`bd-sub\` take no props. All four take their content from the
+default slot.
+
+### Why not plain sup and sub
+The browser's own \`sup\` and \`sub\` shift text with \`vertical-align\`, which grows
+the line box — an annotated line then sits further from its neighbours than the
+rest of the paragraph. These set their own font size and use a relative offset
+instead, so leading stays even down the column.
+        `
+      }
+    }
+  },
+  argTypes: {
+    href: {
+      control    : 'text',
+      description: 'Destination for bd-footnote and bd-citation. Omit to render unlinked.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Navigation' }
+    }
+  }
+};
+
+export const Footnote = () => html`
+    Blocks 99.8% of threats<bd-footnote href="#n1">1</bd-footnote>
+  `;
+
+export const Citation = () => html`
+    See the <bd-citation href="#">2026 Threat Report</bd-citation>.
+  `;
+
+export const Maths = () => html`
+    E = mc<bd-sup>2</bd-sup> · H<bd-sub>2</bd-sub>O
+  `;

package/src/components/architecture.stories.js

@@ -0,0 +1,285 @@
+import { html } from 'lit';
+import { docsPage, refSection } from '../tokens/story-chrome.js';
+
+/**
+ * The canonical layer model, written so it can be read without knowing the
+ * P5/P6 remediation history.
+ *
+ * Documentation only: this file renders no product component and owns no
+ * contract. It is filed under its own group rather than under `Atoms/` or
+ * `Components/` on purpose -- `lint:tokens` reads the atom tier from a story's
+ * `title`, and `verify:typography` builds its population from the same two
+ * prefixes, so a documentation page filed under either would either claim to
+ * be vocabulary or add itself to a contract gate.
+ */
+export default {
+  title: 'Foundations/Layer Model',
+  tags : ['autodocs']
+};
+
+const LAYERS = [
+  {
+    layer: 'Foundations',
+    owns : 'Design tokens, the scales they are read through, semantic roles, and the governance that keeps them honest.',
+    is   : 'Values and the rules for choosing between them. Nothing here renders product UI.',
+    isNot: 'A place for components. A token is not a component with one property.',
+    here : '--color-*, --spacing-* / --dimension-*, --status-*, --focus-*, --indicator-*, the typography roles, ' +
+           'token-scales.js, and the Design Tokens pages that document them.',
+    rule: 'Never a literal where a token exists; never a token from the wrong category; never a fallback for a design token.'
+  },
+  {
+    layer: 'Atoms',
+    owns : 'Published single-responsibility UI vocabulary, each with its own semantic and accessibility contract.',
+    is   : 'One responsibility, documentable on its own, meaningful to a consumer outside this repository. ' +
+            'An atom may own behaviour -- a checkbox has state, bd-back navigates -- as long as the behaviour is its ' +
+            'own responsibility rather than the orchestration of other UI objects.',
+    isNot: 'Anything that is merely small. Anything whose job is to arrange other objects.',
+    here : 'bd-h, bd-p, bd-link, bd-button, bd-badge, bd-divider-*, bd-img, the icon family, the form controls, ' +
+           'bd-alert, bd-progress, bd-tooltip, bd-back, bd-visually-hidden.',
+    rule: 'In-repo reuse is NOT a requirement. See "Zero consumers" below.'
+  },
+  {
+    layer: 'Components',
+    owns : 'Reusable composed UI objects: several responsibilities together, or real behaviour and state, ' +
+           'still meaningful outside any one page section.',
+    is   : 'A UI object a page can use more than once, in more than one place.',
+    isNot: 'Something classified here merely because it contains another custom element. Containment is not composition.',
+    here : 'bd-accordion, bd-tabs, bd-tab-list, bd-modal, bd-carousel, bd-video-player, bd-breadcrumb, ' +
+           'bd-page-switcher, bd-anchor-nav, bd-compatibility-table, bd-quick-answer, bd-card-item, bd-terminal-message.',
+    rule: 'A component is not required to be built only from atoms. Local implementation is often correct.'
+  },
+  {
+    layer: 'Modules',
+    owns : 'Page-level compositions whose responsibility is a meaningful content or marketing section.',
+    is   : 'A section of a page: usually one instance per page, with a title, a description and a body it owns.',
+    isNot: 'A reusable primitive. Do not split a module into invented components to improve a composition metric.',
+    here : 'bd-trust-panel, bd-process-steps, bd-overview, bd-cta-banner, bd-comparison-panel, bd-agent-endpoints, ' +
+           'bd-awards-section (and its two variants), bd-terms-section, bd-bento-grid, bd-card-features-section.',
+    rule: 'Modules MAY compose atoms directly. They do so today and it is correct -- see "Modules and atoms" below.'
+  },
+  {
+    layer: 'Layout',
+    owns : 'Reusable layout responsibility, where one genuinely exists.',
+    is   : 'An API that expresses arrangement -- columns, gap, alignment -- and carries no content semantics.',
+    isNot: 'A wrapper around display:flex. A section that happens to use a grid internally is a Module, not Layout.',
+    here : 'bd-grid, and today nothing else. bd-bento-grid is a Module: it takes eyebrow, title and description, ' +
+           'so it arranges content it also owns.',
+    rule: 'Layout stays local CSS unless a stable arrangement responsibility is demonstrated with evidence.'
+  },
+  {
+    layer: 'Internal primitives',
+    owns : 'Reusable implementation mechanisms that are deliberately NOT public UI vocabulary.',
+    is   : 'A keyboard map, a resolver, a derived formula, a base class, a shared stylesheet fragment.',
+    isNot: 'An atom. These have no element, no story and no public contract, and that is the point.',
+    here : 'shared/form-field.css.js (control height = padding·2 + fontSize × lineHeight), shared/token-scales.js, ' +
+           'shared/prop-vocabulary.js (size · variant · tone), accordion/accordion-keyboard.js, ' +
+           'icons/icon-element.js (BdIconElement).',
+    rule: 'Prefer this over a public atom when the shared thing is a mechanism rather than a UI object. ' +
+           'It is the layer with the best record here: five primitives, all healthy, no public surface.'
+  }
+];
+
+const layerTable = () => html`
+  <table class="ref">
+    <thead>
+      <tr><th>Layer</th><th>Owns</th><th>What belongs</th><th>What does not</th></tr>
+    </thead>
+    <tbody>
+      ${LAYERS.map(l => html`
+        <tr>
+          <td><strong>${l.layer}</strong></td>
+          <td>${l.owns}</td>
+          <td>${l.is}<br><em>${l.here}</em></td>
+          <td>${l.isNot}<br><strong>Rule:</strong> ${l.rule}</td>
+        </tr>
+      `)}
+    </tbody>
+  </table>
+`;
+
+const COMPOSITION = [
+  ['An existing atom MUST be used',
+    'Heading or body copy (bd-h / bd-p -- already used by 22 and 21 components), an inline navigational link, ' +
+   'a tintable interface icon that already exists in icons/, or a form control.'],
+  ['Local implementation is correct',
+    'Layout. Chrome controls that carry no variant contract -- a modal close, a footer nav toggle. ' +
+   'Marks a control owns, like a checkbox tick or a play triangle. Decorative artwork. Anything the ' +
+   'component’s own behaviour owns.'],
+  ['Repeated responsibility triggers an atom review',
+    'When the same responsibility -- not the same markup -- appears in THREE independent non-frozen components ' +
+   'and they agree on semantics and accessibility. Three, not two: at two, this library has consistently been ' +
+   'better off leaving it local.'],
+  ['Shared behaviour belongs in an internal primitive',
+    'When the shared thing is a mechanism rather than a UI object. accordion-keyboard.js is the model: two item ' +
+   'classes share one keyboard contract with no element and no public API.'],
+  ['Modules may compose atoms directly',
+    'Yes. Do not invent a wrapper component so a section only ever touches components.'],
+  ['Layout stays CSS, or becomes vocabulary',
+    'It stays CSS unless it encodes a stable arrangement responsibility with a token behind it. ' +
+   '165 flex and 187 gap declarations across 52 files are shorthand, not a responsibility.'],
+  ['Evidence required for a new Atom',
+    'A clear single responsibility; coherent accessibility ownership; an API that can stay small; ' +
+   'parents that do not need extensive overrides to reproduce today’s behaviour; and it must remove ' +
+   'duplicated behaviour or semantics rather than duplicated markup.'],
+  ['Evidence required for a new Component',
+    'Two or more genuinely distinct uses, behaviour or composition beyond a single atom responsibility, ' +
+   'and meaning outside one page section.'],
+  ['Evidence required for a new Module',
+    'A real page section with content it owns. Modules are written, not abstracted.'],
+  ['PRODUCT_FROZEN',
+    'pricing-cards is frozen by product decision. Report findings there; change nothing. It is the largest local ' +
+   'reimplementer in the library and none of it is actionable.']
+];
+
+const A11Y = [
+  ['role', 'The atom, wherever an atom exists. bd-alert owns alert/status, bd-progress owns progressbar, bd-tooltip owns tooltip.'],
+  ['accessible name', 'The atom that renders the control. Where a label can be empty, the host forwards aria-label to the real control -- bd-back is the worked example.'],
+  ['keyboard behaviour', 'The component. Shared keyboard contracts live in an internal primitive, not an atom.'],
+  ['focus behaviour', 'The component. The visual focus owner and the DOM focus owner may differ deliberately: the accordion paints the ring on the whole item while the button stays the focus target.'],
+  ['ARIA value semantics', 'Whoever genuinely has a value. A component whose geometry is not proportional to its value should not claim a value role -- see below.'],
+  ['live regions', 'The atom that owns the message. Two components independently implementing the same live-region rule is duplication, not defence.']
+];
+
+export const LayerModel = () =>
+  docsPage({
+    title: 'Layer model',
+    lede : 'Foundations, Atoms, Components, Modules, Layout, and internal primitives — what each one owns in ' +
+           'this repository, with the rules for adding to them. Derived from the library as it stands, not from a ' +
+           'textbook hierarchy.',
+    note: html`This page is documentation. It is filed under its own group because
+      <code>lint:tokens</code> reads the atom tier from a story&rsquo;s <code>title</code>, and
+      <code>verify:typography</code> builds its population from the <code>Atoms/</code> and
+      <code>Components/</code> prefixes — so where a page is filed changes what the gates believe.`,
+    children: html`
+      ${refSection({ name: 'The six layers', meta: 'what belongs where', children: layerTable() })}
+
+      ${refSection({
+        name    : 'Composition contract',
+        meta    : 'when to reach for an atom, and when not to',
+        children: html`
+          <table class="ref">
+            <thead><tr><th>Question</th><th>Answer</th></tr></thead>
+            <tbody>${COMPOSITION.map(([q, a]) => html`<tr><td><strong>${q}</strong></td><td>${a}</td></tr>`)}</tbody>
+          </table>
+          <p><strong>One rule this system deliberately does NOT have:</strong> &ldquo;components must be composed only
+          from atoms&rdquo;. The evidence does not support it. The median component here composes two atoms and
+          implements the rest locally, and that is usually the right answer rather than a defect.</p>
+        `
+      })}
+
+      ${refSection({
+        name    : 'Accessibility ownership',
+        meta    : 'who owns which contract',
+        children: html`
+          <table class="ref">
+            <thead><tr><th>Responsibility</th><th>Owner</th></tr></thead>
+            <tbody>${A11Y.map(([r, o]) => html`<tr><td><strong>${r}</strong></td><td>${o}</td></tr>`)}</tbody>
+          </table>
+          <p>Used as a test: <strong>an abstraction that cannot clearly own its accessibility responsibility is
+          probably not an atom.</strong></p>
+        `
+      })}
+
+      ${refSection({
+        name    : 'Misleading visual similarity',
+        meta    : 'the negative example, kept on purpose',
+        children: html`
+          <p><code>bd-progress</code> and <code>compare-bar</code> both draw a coloured horizontal bar in a rounded
+          track with a label. They share no responsibility, and the measurement is what proves it.</p>
+          <table class="ref">
+            <thead><tr><th></th><th>bd-progress</th><th>compare-bar</th></tr></thead>
+            <tbody>
+              <tr><td>fill width vs value</td><td>64 &rarr; 64.0%, 30 &rarr; 30.0%, 100 &rarr; 100.0% — <strong>width is the value</strong></td>
+                  <td>5.59 &rarr; 86.3%, <strong>5.89 &rarr; 71.4%</strong> — <strong>not even monotonic</strong></td></tr>
+              <tr><td>why</td><td>value / max, linear</td>
+                  <td>per-card reference score through a gamma-shaped stretch; <code>variant="primary"</code> is pinned at 100%</td></tr>
+              <tr><td>ARIA</td><td><code>role="progressbar"</code> with <code>aria-valuenow/min/max</code></td>
+                  <td>no role; the value reaches the tree only as a sentence on a generic node</td></tr>
+              <tr><td>track</td><td>8px, label above it</td><td>48px row, label and score inside the fill</td></tr>
+              <tr><td>colour</td><td><code>--status-*-accent</code> — tone carries meaning</td>
+                  <td><code>--cs-bar-primary-bg</code> — brand and theme identity</td></tr>
+            </tbody>
+          </table>
+          <p>The compare section says so in its own visible copy: <em>&ldquo;Bar lengths are scaled for visibility
+          between brands.&rdquo;</em> One is a measurement; the other is deliberately not. A shared
+          &ldquo;track + fill&rdquo; primitive would have to make them agree about the only thing that matters, and it
+          could not own value semantics for both. <strong>So there is no shared primitive, and this pair is the standing
+          reminder that appearance does not establish responsibility.</strong></p>
+        `
+      })}
+
+      ${refSection({
+        name    : 'Zero consumers does not mean dead',
+        meta    : 'why the atom tier looks unused',
+        children: html`
+          <p>33 of the 65 elements filed under <code>Atoms/</code> have <strong>no consumer inside this
+          repository</strong>. None of them is dead: 62 of 65 are reachable from the package&rsquo;s public exports, and
+          the consumers of this library are external pages.</p>
+          <p>The <code>Atoms/</code> tier is a <strong>published vocabulary and documentation layer</strong> before it is
+          an internal composition layer. Every form atom sits in this group — coherently, because this package ships
+          forms while its own marketing components contain none.</p>
+          <p><strong>Do not delete or demote an atom on consumer count.</strong> The question is whether it owns a
+          coherent responsibility and contract, not whether anything here happens to call it.</p>
+        `
+      })}
+
+      ${refSection({
+        name    : 'Where classification lives',
+        meta    : 'and why it is not the Storybook title',
+        children: html`
+          <p>A unit&rsquo;s layer is recorded in <code>scripts/architecture.json</code>, keyed on its
+          <strong>source path</strong>. Both governance gates read it from there: <code>lint:tokens</code> asks which
+          files are atom-tier, and <code>verify:typography</code> asks which stories are a typography contract.</p>
+          <table class="ref">
+            <thead><tr><th>Rule</th><th>Why</th></tr></thead>
+            <tbody>
+              <tr><td><strong>Architecture layer &ne; Storybook navigation path</strong></td>
+                  <td>Both gates used to read the layer out of the title. Filing the module stories under
+                  <code>Modules/</code> would have taken the typography population from 572 stories to 479 with the
+                  gate still green. A presentation name must never decide what gets enforced.</td></tr>
+              <tr><td><strong>Architecture layer &ne; gate participation</strong></td>
+                  <td>Two separate fields. <code>src/components/atoms.stories.js</code> is <code>FOUNDATION</code> and
+                  <code>typography: true</code>: documentation by responsibility, but it renders real atoms at real
+                  sizes, so it is still a typography contract.</td></tr>
+              <tr><td><strong>A Module is not an exemption</strong></td>
+                  <td>Every <code>MODULE</code> unit is <code>typography: true</code>. Page-level composition still has
+                  headings and body copy with real leading.</td></tr>
+              <tr><td><strong>A new Atom or Component</strong></td>
+                  <td>Add one entry for its directory. Until then <code>check:architecture</code> fails with
+                  <em>unclassified</em> — there is deliberately no fallback entry for <code>src/components</code>,
+                  because a fallback would silently classify the next thing somebody adds.</td></tr>
+              <tr><td><strong>When a Storybook title changes</strong></td>
+                  <td>Nothing happens to enforcement, and that has now been done rather than argued.
+                  P6D.3 moved 35 titles into this taxonomy — <code>bd-tab-list</code> from
+                  <code>Atoms/</code> to <code>Components/</code>, <code>bd-grid</code> to <code>Layout/</code>,
+                  thirteen page-level sections to <code>Modules/</code> — and the typography population stayed at
+                  572 stories, the same 572, with atom-tier enforcement unchanged at 132 files.</td></tr>
+              <tr><td><strong>Stale and missing entries</strong></td>
+                  <td>Checked both ways, like <code>breakpoint-exceptions.json</code>: an entry whose path has gone
+                  fails as <em>stale</em>, a shipped file with no entry fails as <em>unclassified</em>, and an invalid
+                  layer or a non-boolean flag fails too. <code>check:architecture --negative-control</code> proves each
+                  one still fails.</td></tr>
+              <tr><td><strong>The population floor</strong></td>
+                  <td><code>typographyPopulationFloor</code> records how many stories the gate must cover. It fails
+                  below and reports above, so a gate can no longer quietly check less — a reduction has to be argued
+                  for in a diff.</td></tr>
+            </tbody>
+          </table>
+        `
+      })}
+
+      ${refSection({
+        name    : 'Modules and atoms',
+        meta    : 'already true, not a proposal',
+        children: html`
+          <p>The AI Guardian landing demo composes atoms directly and heavily: <code>bd-p</code> 19 times,
+          <code>bd-link</code> 18, <code>bd-button-link</code> 6, <code>bd-divider-vertical</code> 4, plus the icon
+          family — alongside modules such as <code>bd-trust-panel</code>, <code>bd-process-steps</code> and
+          <code>bd-cta-banner</code>.</p>
+          <p>A page-level composition reaching for a heading or a link is not a layering violation. Requiring modules to
+          go through components would add wrappers that carry no responsibility.</p>
+        `
+      })}
+    `
+  });
+LayerModel.storyName = 'Layer model';