@jaimevalasek/aioson 1.30.0 → 1.30.2

package/template/.aioson/skills/design/bold-editorial-ui/references/design-tokens.md

@@ -1,326 +1,326 @@
-# Design Tokens — Bold Editorial UI
-
-All CSS custom properties for the Bold Editorial system. Apply these to the root `:root` or a `[data-theme]` container.
-
-**Token scope rule**: always declare tokens on the topmost shared ancestor, never inline. Never hardcode a color, font, or size that has a token equivalent.
-
----
-
-## Font Imports
-
-```css
-/* Clash Display — Fontshare (free for commercial use) */
-@import url('https://api.fontshare.com/v2/css?f[]=clash-display@200;300;400;500;600;700&display=swap');
-
-/* Fallback if Fontshare unavailable: Cabinet Grotesk or Syne */
-/* @import url('https://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800&display=swap'); */
-
-/* Body + Mono */
-@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap');
-```
-
----
-
-## Typography Tokens
-
-```css
-:root {
-  /* Font families */
-  --font-display: 'Clash Display', 'Cabinet Grotesk', 'Syne', Impact, "Arial Black", system-ui, sans-serif;
-  --font-body:    'Inter', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
-  --font-mono:    'JetBrains Mono', 'Space Mono', ui-monospace, 'Courier New', monospace;
-
-  /* Font sizes — editorial scale, larger than most systems */
-  --text-xs:   0.75rem;    /* 12px — mono metadata, captions */
-  --text-sm:   0.875rem;   /* 14px — body small */
-  --text-base: 1rem;       /* 16px — body */
-  --text-lg:   1.25rem;    /* 20px — lead paragraph */
-  --text-xl:   1.5rem;     /* 24px — subheadings */
-  --text-2xl:  2rem;       /* 32px — section titles */
-  --text-3xl:  3rem;       /* 48px — page headlines */
-  --text-4xl:  4.5rem;     /* 72px — hero headlines */
-  --text-5xl:  6rem;       /* 96px — statement text */
-  --text-6xl:  8rem;       /* 128px — manifesto / display — maximum impact */
-
-  /* Font weights */
-  --weight-regular:   400;
-  --weight-medium:    500;
-  --weight-semibold:  600;
-  --weight-bold:      700;
-
-  /* Line heights */
-  --leading-none:    0.9;    /* text-5xl, text-6xl — tight for display */
-  --leading-tight:   1.05;   /* text-4xl — headlines */
-  --leading-snug:    1.2;    /* text-3xl, text-2xl */
-  --leading-normal:  1.5;    /* text-lg, text-xl — comfortable reading */
-  --leading-relaxed: 1.65;   /* text-base — body */
-  --leading-loose:   2;      /* text-sm, text-xs in tables */
-
-  /* Letter spacing */
-  --tracking-tighter: -0.04em;  /* display headings at large sizes */
-  --tracking-tight:   -0.02em;  /* section headlines */
-  --tracking-normal:   0;
-  --tracking-wide:     0.05em;  /* subheadings, labels */
-  --tracking-wider:    0.08em;  /* mono labels, uppercase */
-  --tracking-widest:   0.15em;  /* mono overlines, badges, category text */
-}
-```
-
-### Typography usage rules
-
-- `--font-display` for all headlines `text-2xl` and above. Never use body font for display sizes.
-- `--font-body` for all body copy, descriptions, form labels, navigation.
-- `--font-mono` for all overlines, category labels, dates, version badges, metadata, code. This is non-negotiable.
-- At `text-5xl` and `text-6xl`: always `line-height: var(--leading-none)` + `letter-spacing: var(--tracking-tighter)`.
-- At `text-3xl` and `text-4xl`: `line-height: var(--leading-tight)` + `letter-spacing: var(--tracking-tight)`.
-- Mono text: always `uppercase` + `letter-spacing: var(--tracking-widest)`.
-
----
-
-## Color Tokens — Dark Theme (default)
-
-```css
-[data-theme="dark"],
-:root {
-  /* Backgrounds — near-black, not navy or warm */
-  --bg-void:      #050505;
-  --bg-base:      #0A0A0A;
-  --bg-surface:   #141414;
-  --bg-elevated:  #1E1E1E;
-  --bg-overlay:   #282828;
-
-  /* Text */
-  --text-heading:   #FFFFFF;
-  --text-primary:   #B8B8B8;
-  --text-secondary: #787878;
-  --text-muted:     #484848;
-  --text-inverse:   #0A0A0A;   /* for text on light surfaces */
-
-  /* Accent — red-orange, energetic */
-  --accent:          #FF4D2A;
-  --accent-strong:   #E03A18;
-  --accent-dim:      rgba(255, 77, 42, 0.15);
-  --accent-hover:    #FF6647;
-  --accent-contrast: #FFFFFF;
-
-  /* Borders */
-  --border-subtle:   rgba(255, 255, 255, 0.06);
-  --border-medium:   rgba(255, 255, 255, 0.12);
-  --border-strong:   rgba(255, 255, 255, 0.22);
-
-  /* Semantic */
-  --semantic-green:        #22C55E;
-  --semantic-green-dim:    rgba(34, 197, 94, 0.15);
-  --semantic-amber:        #F59E0B;
-  --semantic-amber-dim:    rgba(245, 158, 11, 0.15);
-  --semantic-red:          #EF4444;
-  --semantic-red-dim:      rgba(239, 68, 68, 0.15);
-  --semantic-blue:         #60A5FA;
-  --semantic-blue-dim:     rgba(96, 165, 250, 0.15);
-  --semantic-purple:       #A78BFA;
-  --semantic-purple-dim:   rgba(167, 139, 250, 0.15);
-}
-```
-
----
-
-## Color Tokens — Light Theme
-
-```css
-[data-theme="light"] {
-  /* Backgrounds — off-white, slightly cool */
-  --bg-void:      #F5F5F0;
-  --bg-base:      #FAFAF7;
-  --bg-surface:   #FFFFFF;
-  --bg-elevated:  #EFEFEA;
-  --bg-overlay:   #E5E5DF;
-
-  /* Text */
-  --text-heading:   #0A0A0A;
-  --text-primary:   #3A3A3A;
-  --text-secondary: #7A7A7A;
-  --text-muted:     #AAAAAA;
-  --text-inverse:   #FFFFFF;
-
-  /* Accent — deeper red-orange for light backgrounds */
-  --accent:          #E03A18;
-  --accent-strong:   #C42E0F;
-  --accent-dim:      rgba(224, 58, 24, 0.10);
-  --accent-hover:    #FF4D2A;
-  --accent-contrast: #FFFFFF;
-
-  /* Borders */
-  --border-subtle:   rgba(0, 0, 0, 0.06);
-  --border-medium:   rgba(0, 0, 0, 0.12);
-  --border-strong:   rgba(0, 0, 0, 0.22);
-
-  /* Semantic */
-  --semantic-green:        #16A34A;
-  --semantic-green-dim:    rgba(22, 163, 74, 0.10);
-  --semantic-amber:        #D97706;
-  --semantic-amber-dim:    rgba(217, 119, 6, 0.10);
-  --semantic-red:          #DC2626;
-  --semantic-red-dim:      rgba(220, 38, 38, 0.10);
-  --semantic-blue:         #2563EB;
-  --semantic-blue-dim:     rgba(37, 99, 235, 0.10);
-  --semantic-purple:       #7C3AED;
-  --semantic-purple-dim:   rgba(124, 58, 237, 0.10);
-}
-```
-
----
-
-## Shadow Tokens
-
-```css
-:root {
-  /* Dark theme — deep cinematic shadows */
-  --shadow-xs:    0 1px 4px rgba(0, 0, 0, 0.20);
-  --shadow-sm:    0 2px 8px rgba(0, 0, 0, 0.25);
-  --shadow-md:    0 8px 24px rgba(0, 0, 0, 0.35);
-  --shadow-lg:    0 16px 48px rgba(0, 0, 0, 0.45);
-  --shadow-xl:    0 24px 64px rgba(0, 0, 0, 0.55);
-
-  /* Accent glow — ONE element per viewport maximum */
-  --shadow-glow:  0 0 60px rgba(255, 77, 42, 0.15);
-
-  /* Light theme shadows — visible but measured */
-  --shadow-xs-light:  0 1px 3px rgba(0, 0, 0, 0.08);
-  --shadow-sm-light:  0 2px 8px rgba(0, 0, 0, 0.10);
-  --shadow-md-light:  0 8px 24px rgba(0, 0, 0, 0.12);
-  --shadow-lg-light:  0 16px 48px rgba(0, 0, 0, 0.14);
-}
-```
-
-Shadow rules:
-- On dark theme: use `--shadow-*` (black-based).
-- On light theme: use `--shadow-*-light` (softer).
-- `--shadow-glow` is for ONE featured element per viewport (hero CTA, featured pricing card). Never apply to more than one element in the same scroll viewport.
-
----
-
-## Spacing Tokens
-
-```css
-:root {
-  --space-1:  0.25rem;    /*  4px */
-  --space-2:  0.5rem;     /*  8px */
-  --space-3:  0.75rem;    /* 12px */
-  --space-4:  1rem;       /* 16px */
-  --space-5:  1.25rem;    /* 20px */
-  --space-6:  1.5rem;     /* 24px */
-  --space-8:  2rem;       /* 32px */
-  --space-10: 2.5rem;     /* 40px */
-  --space-12: 3rem;       /* 48px */
-  --space-16: 4rem;       /* 64px */
-  --space-20: 5rem;       /* 80px */
-  --space-24: 6rem;       /* 96px */
-  --space-32: 8rem;       /* 128px — hero and editorial sections */
-  --space-40: 10rem;      /* 160px — maximum editorial breathing room */
-}
-```
-
----
-
-## Border Radius Tokens
-
-```css
-:root {
-  /* Minimal radius — editorial and adult, not bubbly */
-  --radius-sm:   0.25rem;    /*  4px — badges, chips */
-  --radius-md:   0.375rem;   /*  6px — buttons (default) */
-  --radius-lg:   0.5rem;     /*  8px — cards (default) */
-  --radius-xl:   0.75rem;    /* 12px — modals, larger containers */
-  --radius-2xl:  1rem;       /* 16px — featured cards, hero containers */
-  --radius-full: 9999px;     /* pills — used sparingly */
-}
-```
-
-Radius rules:
-- Default radius for cards: `--radius-lg` (8px).
-- Default radius for buttons: `--radius-md` (6px).
-- Never exceed `--radius-2xl` (16px) in this system — no warm-craft-style extreme rounding.
-- `--radius-full` is allowed for badge pills and avatar circles only.
-
----
-
-## Layout Tokens
-
-```css
-:root {
-  /* Content widths */
-  --content-xs:   480px;
-  --content-sm:   640px;
-  --content-md:   768px;
-  --content-lg:   1024px;
-  --content-xl:   1280px;
-  --content-full: 1440px;
-
-  /* Breakpoints */
-  --breakpoint-sm:  640px;
-  --breakpoint-md:  768px;
-  --breakpoint-lg:  1024px;
-  --breakpoint-xl:  1280px;
-  --breakpoint-2xl: 1536px;
-
-  /* Z-index scale */
-  --z-below:   -1;
-  --z-base:     0;
-  --z-raised:   10;
-  --z-overlay:  20;
-  --z-sticky:   30;
-  --z-fixed:    40;
-  --z-modal:    50;
-  --z-toast:    60;
-  --z-tooltip:  70;
-}
-```
-
----
-
-## Transition Tokens
-
-```css
-:root {
-  --transition-fast:  100ms ease;
-  --transition-base:  200ms ease;
-  --transition-slow:  400ms cubic-bezier(0.16, 1, 0.3, 1);
-  --transition-hero:  800ms cubic-bezier(0.16, 1, 0.3, 1);
-
-  /* Theme switch — all affected properties together */
-  --transition-theme: background-color 200ms ease,
-                      color 200ms ease,
-                      border-color 200ms ease,
-                      box-shadow 200ms ease;
-}
-```
-
----
-
-## Token Scope Guardrails
-
-| What | Rule |
-|------|------|
-| Background colors | Only `--bg-*` tokens. Never hardcode hex for surfaces. |
-| Text colors | Only `--text-*` tokens. Never `color: white` or `color: #fff` inline. |
-| Accent usage | `--accent` for CTAs, active states, single highlights. Never for borders, background sections, or repeated decorative elements. |
-| `--shadow-glow` | One element per scroll viewport. The hero CTA or featured card. |
-| Font sizes | Only `--text-*` scale tokens. Never arbitrary `font-size: 53px`. |
-| Spacing | Only `--space-*` tokens. Never arbitrary `margin: 17px`. |
-| Border radius | Only `--radius-*` tokens. Never `border-radius: 10px` inline. |
-| Borders | Only `--border-*` tokens. Never `border: 1px solid rgba(...)` inline. |
-| Shadows | Only `--shadow-*` tokens. Never arbitrary `box-shadow` values. |
-
----
-
-## Interaction Guardrails
-
-| Rule | Why |
-|------|-----|
-| Never use blue as accent | This is red-orange. Blue breaks the visual DNA instantly. |
-| Never use warm beige (`#FDF8F0`) as base | That belongs to Warm Craft. Bold Editorial uses cool off-whites. |
-| Never use `border-radius > --radius-2xl` | Sharp edges define this system. Extreme rounding destroys the editorial feel. |
-| Never use blur/glass effects | That belongs to Glassmorphism UI. Bold Editorial surfaces are opaque. |
-| Never use `--shadow-glow` on more than one element per viewport | The glow exists to draw the eye. If everything glows, nothing does. |
-| Mono captions are mandatory for all metadata | Overlines, categories, timestamps, version tags — always `--font-mono` + `uppercase` + wide tracking. |
-| Serif fonts prohibited | Source Serif belongs to Warm Craft. Bold Editorial uses display sans and body sans only. |
+# Design Tokens — Bold Editorial UI
+
+All CSS custom properties for the Bold Editorial system. Apply these to the root `:root` or a `[data-theme]` container.
+
+**Token scope rule**: always declare tokens on the topmost shared ancestor, never inline. Never hardcode a color, font, or size that has a token equivalent.
+
+---
+
+## Font Imports
+
+```css
+/* Clash Display — Fontshare (free for commercial use) */
+@import url('https://api.fontshare.com/v2/css?f[]=clash-display@200;300;400;500;600;700&display=swap');
+
+/* Fallback if Fontshare unavailable: Cabinet Grotesk or Syne */
+/* @import url('https://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800&display=swap'); */
+
+/* Body + Mono */
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap');
+```
+
+---
+
+## Typography Tokens
+
+```css
+:root {
+  /* Font families */
+  --font-display: 'Clash Display', 'Cabinet Grotesk', 'Syne', Impact, "Arial Black", system-ui, sans-serif;
+  --font-body:    'Inter', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+  --font-mono:    'JetBrains Mono', 'Space Mono', ui-monospace, 'Courier New', monospace;
+
+  /* Font sizes — editorial scale, larger than most systems */
+  --text-xs:   0.75rem;    /* 12px — mono metadata, captions */
+  --text-sm:   0.875rem;   /* 14px — body small */
+  --text-base: 1rem;       /* 16px — body */
+  --text-lg:   1.25rem;    /* 20px — lead paragraph */
+  --text-xl:   1.5rem;     /* 24px — subheadings */
+  --text-2xl:  2rem;       /* 32px — section titles */
+  --text-3xl:  3rem;       /* 48px — page headlines */
+  --text-4xl:  4.5rem;     /* 72px — hero headlines */
+  --text-5xl:  6rem;       /* 96px — statement text */
+  --text-6xl:  8rem;       /* 128px — manifesto / display — maximum impact */
+
+  /* Font weights */
+  --weight-regular:   400;
+  --weight-medium:    500;
+  --weight-semibold:  600;
+  --weight-bold:      700;
+
+  /* Line heights */
+  --leading-none:    0.9;    /* text-5xl, text-6xl — tight for display */
+  --leading-tight:   1.05;   /* text-4xl — headlines */
+  --leading-snug:    1.2;    /* text-3xl, text-2xl */
+  --leading-normal:  1.5;    /* text-lg, text-xl — comfortable reading */
+  --leading-relaxed: 1.65;   /* text-base — body */
+  --leading-loose:   2;      /* text-sm, text-xs in tables */
+
+  /* Letter spacing */
+  --tracking-tighter: 0;  /* display headings at large sizes */
+  --tracking-tight:   0;  /* section headlines */
+  --tracking-normal:   0;
+  --tracking-wide:     0.05em;  /* subheadings, labels */
+  --tracking-wider:    0.08em;  /* mono labels, uppercase */
+  --tracking-widest:   0.15em;  /* mono overlines, badges, category text */
+}
+```
+
+### Typography usage rules
+
+- `--font-display` for all headlines `text-2xl` and above. Never use body font for display sizes.
+- `--font-body` for all body copy, descriptions, form labels, navigation.
+- `--font-mono` for all overlines, category labels, dates, version badges, metadata, code. This is non-negotiable.
+- At `text-5xl` and `text-6xl`: always `line-height: var(--leading-none)` + `letter-spacing: var(--tracking-tighter)`.
+- At `text-3xl` and `text-4xl`: `line-height: var(--leading-tight)` + `letter-spacing: var(--tracking-tight)`.
+- Mono text: always `uppercase` + `letter-spacing: var(--tracking-widest)`.
+
+---
+
+## Color Tokens — Dark Theme (default)
+
+```css
+[data-theme="dark"],
+:root {
+  /* Backgrounds — near-black, not navy or warm */
+  --bg-void:      #050505;
+  --bg-base:      #0A0A0A;
+  --bg-surface:   #141414;
+  --bg-elevated:  #1E1E1E;
+  --bg-overlay:   #282828;
+
+  /* Text */
+  --text-heading:   #FFFFFF;
+  --text-primary:   #B8B8B8;
+  --text-secondary: #787878;
+  --text-muted:     #484848;
+  --text-inverse:   #0A0A0A;   /* for text on light surfaces */
+
+  /* Accent — red-orange, energetic */
+  --accent:          #FF4D2A;
+  --accent-strong:   #E03A18;
+  --accent-dim:      rgba(255, 77, 42, 0.15);
+  --accent-hover:    #FF6647;
+  --accent-contrast: #FFFFFF;
+
+  /* Borders */
+  --border-subtle:   rgba(255, 255, 255, 0.06);
+  --border-medium:   rgba(255, 255, 255, 0.12);
+  --border-strong:   rgba(255, 255, 255, 0.22);
+
+  /* Semantic */
+  --semantic-green:        #22C55E;
+  --semantic-green-dim:    rgba(34, 197, 94, 0.15);
+  --semantic-amber:        #F59E0B;
+  --semantic-amber-dim:    rgba(245, 158, 11, 0.15);
+  --semantic-red:          #EF4444;
+  --semantic-red-dim:      rgba(239, 68, 68, 0.15);
+  --semantic-blue:         #60A5FA;
+  --semantic-blue-dim:     rgba(96, 165, 250, 0.15);
+  --semantic-purple:       #A78BFA;
+  --semantic-purple-dim:   rgba(167, 139, 250, 0.15);
+}
+```
+
+---
+
+## Color Tokens — Light Theme
+
+```css
+[data-theme="light"] {
+  /* Backgrounds — off-white, slightly cool */
+  --bg-void:      #F5F5F0;
+  --bg-base:      #FAFAF7;
+  --bg-surface:   #FFFFFF;
+  --bg-elevated:  #EFEFEA;
+  --bg-overlay:   #E5E5DF;
+
+  /* Text */
+  --text-heading:   #0A0A0A;
+  --text-primary:   #3A3A3A;
+  --text-secondary: #7A7A7A;
+  --text-muted:     #AAAAAA;
+  --text-inverse:   #FFFFFF;
+
+  /* Accent — deeper red-orange for light backgrounds */
+  --accent:          #E03A18;
+  --accent-strong:   #C42E0F;
+  --accent-dim:      rgba(224, 58, 24, 0.10);
+  --accent-hover:    #FF4D2A;
+  --accent-contrast: #FFFFFF;
+
+  /* Borders */
+  --border-subtle:   rgba(0, 0, 0, 0.06);
+  --border-medium:   rgba(0, 0, 0, 0.12);
+  --border-strong:   rgba(0, 0, 0, 0.22);
+
+  /* Semantic */
+  --semantic-green:        #16A34A;
+  --semantic-green-dim:    rgba(22, 163, 74, 0.10);
+  --semantic-amber:        #D97706;
+  --semantic-amber-dim:    rgba(217, 119, 6, 0.10);
+  --semantic-red:          #DC2626;
+  --semantic-red-dim:      rgba(220, 38, 38, 0.10);
+  --semantic-blue:         #2563EB;
+  --semantic-blue-dim:     rgba(37, 99, 235, 0.10);
+  --semantic-purple:       #7C3AED;
+  --semantic-purple-dim:   rgba(124, 58, 237, 0.10);
+}
+```
+
+---
+
+## Shadow Tokens
+
+```css
+:root {
+  /* Dark theme — deep cinematic shadows */
+  --shadow-xs:    0 1px 4px rgba(0, 0, 0, 0.20);
+  --shadow-sm:    0 2px 8px rgba(0, 0, 0, 0.25);
+  --shadow-md:    0 8px 24px rgba(0, 0, 0, 0.35);
+  --shadow-lg:    0 16px 48px rgba(0, 0, 0, 0.45);
+  --shadow-xl:    0 24px 64px rgba(0, 0, 0, 0.55);
+
+  /* Accent glow — ONE element per viewport maximum */
+  --shadow-glow:  0 0 60px rgba(255, 77, 42, 0.15);
+
+  /* Light theme shadows — visible but measured */
+  --shadow-xs-light:  0 1px 3px rgba(0, 0, 0, 0.08);
+  --shadow-sm-light:  0 2px 8px rgba(0, 0, 0, 0.10);
+  --shadow-md-light:  0 8px 24px rgba(0, 0, 0, 0.12);
+  --shadow-lg-light:  0 16px 48px rgba(0, 0, 0, 0.14);
+}
+```
+
+Shadow rules:
+- On dark theme: use `--shadow-*` (black-based).
+- On light theme: use `--shadow-*-light` (softer).
+- `--shadow-glow` is for ONE featured element per viewport (hero CTA, featured pricing card). Never apply to more than one element in the same scroll viewport.
+
+---
+
+## Spacing Tokens
+
+```css
+:root {
+  --space-1:  0.25rem;    /*  4px */
+  --space-2:  0.5rem;     /*  8px */
+  --space-3:  0.75rem;    /* 12px */
+  --space-4:  1rem;       /* 16px */
+  --space-5:  1.25rem;    /* 20px */
+  --space-6:  1.5rem;     /* 24px */
+  --space-8:  2rem;       /* 32px */
+  --space-10: 2.5rem;     /* 40px */
+  --space-12: 3rem;       /* 48px */
+  --space-16: 4rem;       /* 64px */
+  --space-20: 5rem;       /* 80px */
+  --space-24: 6rem;       /* 96px */
+  --space-32: 8rem;       /* 128px — hero and editorial sections */
+  --space-40: 10rem;      /* 160px — maximum editorial breathing room */
+}
+```
+
+---
+
+## Border Radius Tokens
+
+```css
+:root {
+  /* Minimal radius — editorial and adult, not bubbly */
+  --radius-sm:   0.25rem;    /*  4px — badges, chips */
+  --radius-md:   0.375rem;   /*  6px — buttons (default) */
+  --radius-lg:   0.5rem;     /*  8px — cards (default) */
+  --radius-xl:   0.75rem;    /* 12px — modals, larger containers */
+  --radius-2xl:  1rem;       /* 16px — featured cards, hero containers */
+  --radius-full: 9999px;     /* pills — used sparingly */
+}
+```
+
+Radius rules:
+- Default radius for cards: `--radius-lg` (8px).
+- Default radius for buttons: `--radius-md` (6px).
+- Never exceed `--radius-2xl` (16px) in this system — no warm-craft-style extreme rounding.
+- `--radius-full` is allowed for badge pills and avatar circles only.
+
+---
+
+## Layout Tokens
+
+```css
+:root {
+  /* Content widths */
+  --content-xs:   480px;
+  --content-sm:   640px;
+  --content-md:   768px;
+  --content-lg:   1024px;
+  --content-xl:   1280px;
+  --content-full: 1440px;
+
+  /* Breakpoints */
+  --breakpoint-sm:  640px;
+  --breakpoint-md:  768px;
+  --breakpoint-lg:  1024px;
+  --breakpoint-xl:  1280px;
+  --breakpoint-2xl: 1536px;
+
+  /* Z-index scale */
+  --z-below:   -1;
+  --z-base:     0;
+  --z-raised:   10;
+  --z-overlay:  20;
+  --z-sticky:   30;
+  --z-fixed:    40;
+  --z-modal:    50;
+  --z-toast:    60;
+  --z-tooltip:  70;
+}
+```
+
+---
+
+## Transition Tokens
+
+```css
+:root {
+  --transition-fast:  100ms ease;
+  --transition-base:  200ms ease;
+  --transition-slow:  400ms cubic-bezier(0.16, 1, 0.3, 1);
+  --transition-hero:  800ms cubic-bezier(0.16, 1, 0.3, 1);
+
+  /* Theme switch — all affected properties together */
+  --transition-theme: background-color 200ms ease,
+                      color 200ms ease,
+                      border-color 200ms ease,
+                      box-shadow 200ms ease;
+}
+```
+
+---
+
+## Token Scope Guardrails
+
+| What | Rule |
+|------|------|
+| Background colors | Only `--bg-*` tokens. Never hardcode hex for surfaces. |
+| Text colors | Only `--text-*` tokens. Never `color: white` or `color: #fff` inline. |
+| Accent usage | `--accent` for CTAs, active states, single highlights. Never for borders, background sections, or repeated decorative elements. |
+| `--shadow-glow` | One element per scroll viewport. The hero CTA or featured card. |
+| Font sizes | Only `--text-*` scale tokens. Never arbitrary `font-size: 53px`. |
+| Spacing | Only `--space-*` tokens. Never arbitrary `margin: 17px`. |
+| Border radius | Only `--radius-*` tokens. Never `border-radius: 10px` inline. |
+| Borders | Only `--border-*` tokens. Never `border: 1px solid rgba(...)` inline. |
+| Shadows | Only `--shadow-*` tokens. Never arbitrary `box-shadow` values. |
+
+---
+
+## Interaction Guardrails
+
+| Rule | Why |
+|------|-----|
+| Never use blue as accent | This is red-orange. Blue breaks the visual DNA instantly. |
+| Never use warm beige (`#FDF8F0`) as base | That belongs to Warm Craft. Bold Editorial uses cool off-whites. |
+| Never use `border-radius > --radius-2xl` | Sharp edges define this system. Extreme rounding destroys the editorial feel. |
+| Never use blur/glass effects | That belongs to Glassmorphism UI. Bold Editorial surfaces are opaque. |
+| Never use `--shadow-glow` on more than one element per viewport | The glow exists to draw the eye. If everything glows, nothing does. |
+| Mono captions are mandatory for all metadata | Overlines, categories, timestamps, version tags — always `--font-mono` + `uppercase` + wide tracking. |
+| Serif fonts prohibited | Source Serif belongs to Warm Craft. Bold Editorial uses display sans and body sans only. |