@hegemonart/get-design-done 1.44.0 → 1.46.0

package/reference/responsive.md

@@ -0,0 +1,74 @@
+# Responsive Design - Domain Index
+
+This is the domain entry-point for responsive design. Load this file when the
+interface will render in more than one locale, platform, or viewport condition.
+It covers i18n engineering primitives, RTL and CJK cultural adaptation,
+platform-specific conventions, native token bridging, and performance budgets.
+It does not cover the CSS Grid implementation of responsive layouts (see
+`reference/spatial.md` for container queries and `clamp()`); it does not cover
+copy tone for localized content (see `reference/ux-writing.md`).
+
+---
+
+## Fragment Index
+
+→ **`reference/i18n.md`** (Phase 28) - use when localizing text: expansion
+budgets (+30-40%), CSS logical props, `Intl.*` APIs, ICU MessageFormat,
+bidi isolation, Unicode normalization, multi-script font stacks
+
+→ **`reference/rtl-cjk-cultural.md`** (Phase 28) - use when targeting RTL
+locales or CJK audiences: layout mirroring rules, bidirectional text isolation,
+Arabic/Hebrew/Devanagari rendering, cultural color meanings and imagery norms
+
+→ **`reference/platforms.md`** (Phase 19) - use when targeting multiple
+platforms: iOS/Android/web/visionOS/watchOS nav patterns, safe area insets,
+gesture vocabularies, haptics, native typography conventions
+
+→ **`reference/native-platforms.md`** (Phase 34.1) - use when bridging design
+tokens to native code: canonical CSS token to SwiftUI Color / Compose Color /
+Flutter ThemeData mapping, precision contract for the round-trip
+
+→ **`reference/performance.md`** (Phase 19) - use for any production
+responsive build: Core Web Vitals budgets by project type, JS/font/image
+budgets, React runtime perf rules
+
+→ **`reference/css-grid-layout.md`** (Phase 18) - load the container-queries
+and `clamp()` sections only: fluid responsive components, safe-area insets,
+logical CSS props in Grid context
+
+---
+
+## Rules of Thumb
+
+**1. Size containers for the worst-case expansion locale.**
+Russian and Finnish strings expand +40% from an English baseline. Any text
+container designed at English width will overflow in those locales. Build for
+`EN base x 1.4` as the standard layout-budget rule; top-aligned labels absorb
+expansion without horizontal breakage.
+
+**2. CSS logical properties are the implementation primitive for RTL.**
+Never use `left`/`right` in a layout that will need to mirror. Replace
+`margin-left` with `margin-inline-start`, `padding-right` with
+`padding-inline-end`, and positioned `left` with `inset-inline-start`. The full
+mapping is in `reference/rtl-cjk-cultural.md`.
+
+**3. `prefers-reduced-motion` is a responsive property, not optional.**
+Any animation behind a media query must resolve to `transition: none` or
+`animation-duration: 0.01ms` when the user has set OS-level reduced-motion.
+The CSS reset pattern is in `reference/motion.md`.
+
+**4. Native token precision contract: no re-derivation in component code.**
+Color hex values bridge to native at 8-bit channel precision (no rounding).
+Dimension px values bridge as integer dp/pt. The token-bridge round-trip in
+`reference/native-platforms.md` is the source of truth - any re-derivation
+in component code will drift from the canonical value.
+
+---
+
+## Cross-Domain See Also
+
+- i18n text expansion affects type container sizing: `reference/typography.md`
+- Touch targets differ from pointer targets: `reference/interaction.md`
+- Layout shifts at breakpoints: `reference/spatial.md`
+- OS-level reduced-motion links to animation rules: `reference/motion.md`
+- Civic multi-language government forms: `reference/domains/civic-patterns.md`

package/reference/skill-metadata.md

@@ -0,0 +1,117 @@
+---
+name: skill-metadata
+type: meta-rules
+version: 1.0.0
+phase: 46
+tags: [skill, metadata, frontmatter, single-source-of-truth, generator, description-budget]
+last_updated: 2026-06-02
+---
+
+# Skill Metadata Single Source of Truth
+
+`scripts/lib/manifest/skills.json` is the one place skill frontmatter is authored. A
+generator projects it onto every `source/skills/<id>/SKILL.md`, the build step compiles
+those into the shipped trees, and CI gates keep the three copies identical. This doc
+explains the file, the generator, and the description budget. For the structural rules a
+SKILL.md body must follow (line cap, progressive disclosure, frontmatter required fields),
+see `./skill-authoring-contract.md`.
+
+## What skills.json is
+
+The file is a JSON object: a `schema_version` integer and a `skills` array. Each array
+element is one skill record. Only `name` is required (it must equal the
+`source/skills/<id>/` directory name); every other field is optional and omitted when it
+has no value.
+
+```json
+{
+  "schema_version": 1,
+  "skills": [
+    {
+      "name": "health",
+      "description": "Reports .design/ artifact health - staleness, missing files, token drift, broken state transitions.",
+      "tools": "Read, Bash, Glob, Grep, mcp__gdd_state__get",
+      "disable_model_invocation": true
+    }
+  ]
+}
+```
+
+Recognized record fields: `name`, `description`, `argument_hint`, `tools`,
+`user_invocable`, `disable_model_invocation`, `frontmatter_name` (the `name:` value when it
+is not the default `gdd-<id>`), `extra_frontmatter` (see below), plus `registered_in_phase`
+and `aliases`, which live only in the manifest and never round-trip to frontmatter. The
+schema at `scripts/lib/manifest/schemas/skills.schema.json` validates the shape.
+
+## The build chain
+
+Metadata flows in one direction, and a `*:check` gate guards each hop:
+
+```text
+skills.json
+  -> generate-skill-frontmatter      (npm run generate:skill-frontmatter)
+  -> source/skills/<id>/SKILL.md
+  -> build:skills                     (npm run build:skills)
+  -> skills/  +  dist/claude-code/
+```
+
+`scripts/generate-skill-frontmatter.cjs` rewrites only the frontmatter block of each
+`SKILL.md`, never the markdown body. It has three modes:
+
+- forward (no flag): manifest to frontmatter. The default.
+- `--extract`: the reverse direction, reading current frontmatter back into `skills.json`
+  to seed or refresh the source of truth. Idempotent with forward.
+- `--check`: the CI drift gate. It writes nothing and exits non-zero when any committed
+  frontmatter differs from what the manifest would generate.
+
+`scripts/build-skills.cjs` then propagates `source/skills/` into the committed `skills/`
+tree and `dist/claude-code/`; its own check mode asserts that the built output equals the
+committed output. So the contract is: edit `skills.json`, regenerate, build. Never
+hand-edit a managed frontmatter line in `SKILL.md`, because the drift gate will fail.
+
+## Managed vs preserved fields
+
+The generator owns six frontmatter keys and emits them in this canonical order whenever the
+record carries a value:
+
+1. `name`
+2. `description`
+3. `argument-hint`
+4. `tools`
+5. `user-invocable`
+6. `disable-model-invocation`
+
+String values for `description` and `argument-hint` are always double-quoted on emit, so
+quoting stays uniform across every skill. Anything outside these six keys is not managed.
+The generator carries it verbatim in the record's `extra_frontmatter` array and re-emits it
+after the managed block. The `quality-gate` skill is the working example: its `color`,
+`model`, `default-tier`, `size_budget`, `parallel-safe`, `typical-duration-seconds`,
+`reads-only`, and multi-line `writes:` block all live in `extra_frontmatter` and survive
+every regeneration untouched.
+
+## Description budget
+
+Every `description` must be at least 20 and at most 1024 characters. Two validators enforce
+the ceiling in CI:
+
+- `scripts/validate-skill-length.cjs` treats `DESC_MAX = 1024` as a blocker (it also blocks
+  under 20 characters as under-specification) and is the Phase 28.5 authoring-contract gate.
+- `scripts/lint-agentskills-spec.cjs` rule R4 applies the same 1024-character hard cap from
+  the agentskills.io spec angle, and warns past 200 characters.
+
+Phase 46 keeps that contract intact and wires `npm run lint:agentskills` in as its own
+explicit CI gate, so the spec lint runs on every change rather than only in-process via the
+doctor aggregator.
+
+## How pin consumes it
+
+The `pin`, `unpin`, and `list-pins` skills shipping in this phase read `description`,
+`argument_hint`, and `tools` straight from `skills.json`. That manifest is the pin metadata
+catalogue: the pin surface never live-scrapes a `SKILL.md` or re-derives a description at
+runtime. Reading one structured file keeps pin output consistent with what the generator
+emits, and the `aliases` array is reserved for the pin shortcuts those skills honor.
+
+## See also
+
+- `./skill-authoring-contract.md` for the SKILL.md line cap, description-format guidance,
+  required frontmatter fields, and progressive-disclosure rule.

package/reference/spatial.md

@@ -0,0 +1,38 @@
+# Spatial - Composition, Grid, and Perceptual Organization
+
+Spatial design governs how elements are placed, sized, and related in two-dimensional
+space: composition principles (rule of thirds, focal point, eye-flow), proportion
+derivation (baseline grid, spacing ladder), CSS implementation (Grid, container queries,
+clamp), visual hierarchy, Gestalt grouping, and data presentation. Read this file first,
+then load the specific fragment for the task at hand. Does not cover 3D depth signaling
+via color/shadow as a color decision (see `color.md`) or responsive layout shifts driven
+by locale/platform (see `responsive.md`).
+
+## Fragment Index
+
+| Fragment | When to load |
+|---|---|
+| [`./composition.md`](./composition.md) | choosing a compositional grid (rule of thirds, root rectangles, Fibonacci), placing a focal point, deciding eye-flow archetype (Z / F / Gutenberg) |
+| [`./proportion-systems.md`](./proportion-systems.md) | deriving the baseline grid unit, spacing ladder, icon sizing, corner radius from a single multiplier (4pt / 8pt / sqrt(2)) |
+| [`./css-grid-layout.md`](./css-grid-layout.md) | implementing CSS Grid templates, subgrid, container queries, `clamp()` fluid type, logical props, anchor positioning |
+| [`./visual-hierarchy-layout.md`](./visual-hierarchy-layout.md) | ordering elements by importance: Z-order, whitespace rules, shadow depth, 24 landing archetypes |
+| [`./gestalt.md`](./gestalt.md) | auditing perceptual grouping: proximity, similarity, continuity, closure, figure/ground - 8 principles with scoring rubrics |
+| [`./image-optimization.md`](./image-optimization.md) | images in layout: format matrix, srcset/sizes math, LQIP/BlurHash, CDN transforms, image budget |
+| [`./data-visualization.md`](./data-visualization.md) | charts/dashboards: 25-type chart-choice matrix, color-blind palettes, axis conventions, UUPM dashboard patterns |
+| [`./surfaces.md`](./surfaces.md) | surface treatments: concentric radius formula, optical alignment, 3-layer shadow system, hit area sizing |
+
+## Rules of Thumb
+
+1. Place primary CTAs on the rule-of-thirds power points (the 33%/67% intersections), not dead-center. Centered heroes are the intentional exception, not the default.
+2. Choose one baseline unit for the whole product (4pt, 8pt, or sqrt(2)) and author every spacing, sizing, and radius token as a multiple of it. No one-off values.
+3. CSS Grid container queries (`@container`) should replace media queries for component-level layout. Reserve media queries for page-level breakpoints only.
+4. Gestalt proximity rule: related controls 8px apart or less; unrelated groups 32px apart or more. The layout should communicate relationships before the user reads labels.
+5. Choose the chart type before the color palette. The wrong chart type cannot be rescued by a better palette. Use `data-visualization.md` chart-choice matrix first.
+
+## See Also
+
+- Shadow and elevation as color/depth signal: [`./color.md`](./color.md)
+- Type scale ties into spatial proportion grid: [`./typography.md`](./typography.md)
+- Responsive layout shifts at breakpoints: [`./responsive.md`](./responsive.md)
+- Gestalt grouping informs information architecture: [`./interaction.md`](./interaction.md)
+- Gaming: TV-safe area constraints: [`./domains/gaming-patterns.md`](./domains/gaming-patterns.md)

package/reference/typography.md

@@ -1,5 +1,34 @@
 # Typography - Scale, Pairing, and Hierarchy
 
+This file is the domain index for typography. It covers type-scale construction,
+weight hierarchy, font pairing, and micro-typography. Read `variable-fonts-loading.md`
+when web fonts are in scope. Read `proportion-systems.md` when the full UI grid is
+in scope. Does not cover text-contrast (see `color.md`) or locale text expansion
+(see `responsive.md`, which indexes [`./i18n.md`](./i18n.md) for the per-locale expansion budgets).
+
+## Fragment Index
+
+| Fragment | When to load |
+|---|---|
+| This file (below) | type scale ratios, sizing tokens, weight hierarchy, font pairings, micro-typography |
+| [`./variable-fonts-loading.md`](./variable-fonts-loading.md) | web fonts, `@font-face`, `font-display`, FOIT/FOUT, variable font axes, subsetting, fallback metrics |
+| [`./proportion-systems.md`](./proportion-systems.md) | 4pt/8pt/sqrt(2) baseline grid, spacing ladder, icon sizing, corner radius derivation |
+
+## Rules of Thumb
+
+1. A 1.25 (Major Third) or 1.333 (Perfect Fourth) ratio fits 95% of SaaS products; only reach for 1.618 when visual drama is the explicit brief.
+2. Never author `line-height` as a pixel value - always use a unitless multiplier (1.4-1.6 for body, 1.1-1.2 for headings); unitless values scale with user font-size overrides.
+3. Font weight on the web has only 7 meaningful stops (100-700 in 100-steps); any weight not in the font file rounds to the nearest available - check the variable font `wght` range before specifying 450 or 600.
+4. Baseline-grid lock: every spacing and sizing token should be a multiple of the chosen baseline unit; `padding: 12px` next to body at `16/24` on an 8pt grid is a silent proportion break.
+5. For localized UIs, size type containers for +40% expansion (Russian/Finnish worst-case); top-aligned labels are the only label position that absorbs expansion without layout breakage.
+
+## See Also
+
+- Text contrast and color-blindness checks: [`./color.md`](./color.md)
+- Text expansion in localized UIs: [`./responsive.md`](./responsive.md)
+- Proportion systems tie type to spatial grid: [`./spatial.md`](./spatial.md)
+- Finance number formatting (tabular-nums): [`./domains/finance-patterns.md`](./domains/finance-patterns.md)
+
 ---
 
 ## Type Scale Systems
@@ -35,7 +64,7 @@ Choose a ratio and base size. Common ratios:
 
 Never create a scale ad-hoc. Pick one ratio, generate the scale, use only values in the scale.
 
-**See:** [`./proportion-systems.md`](./proportion-systems.md) §Modular Relationships for how the type scale ties to spacing / sizing / radius scales - when one ratio drives all four scales the whole UI gains a single rhythm rather than four independently-tuned progressions.
+**See:** [`./proportion-systems.md`](./proportion-systems.md) for how the type scale ties to spacing / sizing / radius scales.
 
 ---
 
@@ -43,11 +72,11 @@ Never create a scale ad-hoc. Pick one ratio, generate the scale, use only values
 
 | Context | Line height | Notes |
 |---|---|---|
-| Body text | **1.5 – 1.75** | More generous = more readable |
-| Headings | **1.1 – 1.3** | Tight heading stacks look intentional |
+| Body text | **1.5 - 1.75** | More generous = more readable |
+| Headings | **1.1 - 1.3** | Tight heading stacks look intentional |
 | Captions / small text | **1.4** | Smaller text needs more breathing room |
-| Code blocks | **1.6 – 1.8** | Line scanning for code |
-| Display / hero | **0.9 – 1.1** | Can go very tight for dramatic effect |
+| Code blocks | **1.6 - 1.8** | Line scanning for code |
+| Display / hero | **0.9 - 1.1** | Can go very tight for dramatic effect |
 
 ---
 
@@ -55,9 +84,9 @@ Never create a scale ad-hoc. Pick one ratio, generate the scale, use only values
 
 | Context | Characters per line | Notes |
 |---|---|---|
-| Desktop body | **65 – 75 chars** | Optimal reading comfort |
-| Mobile body | **35 – 55 chars** | Narrower viewport forces shorter |
-| Hero/display | **35 – 55 chars** | Headings should never wrap awkwardly |
+| Desktop body | **65 - 75 chars** | Optimal reading comfort |
+| Mobile body | **35 - 55 chars** | Narrower viewport forces shorter |
+| Hero/display | **35 - 55 chars** | Headings should never wrap awkwardly |
 | Data/tables | No limit | Tables have own structure |
 
 Enforce with `max-width`: `65ch` for body containers works with any font size.
@@ -68,13 +97,13 @@ Enforce with `max-width`: `65ch` for body containers works with any font size.
 
 | Role | Weight | Notes |
 |---|---|---|
-| Display headings | **700 – 900** | Bold commands attention |
-| Page headings | **600 – 700** | Strong but not display-level |
-| Section headings | **500 – 600** | Distinguish from body |
+| Display headings | **700 - 900** | Bold commands attention |
+| Page headings | **600 - 700** | Strong but not display-level |
+| Section headings | **500 - 600** | Distinguish from body |
 | Body text | **400** | Regular - no emphasis weight |
 | UI labels | **500** | Slightly heavier than body |
 | Captions | **400** | Regular - size reduces emphasis |
-| Monospace code | **400 – 500** | |
+| Monospace code | **400 - 500** | |
 
 **Rule**: Never use `font-weight: 300` (light) on small text. It becomes illegible below 16px.
 
@@ -127,7 +156,7 @@ Enforce with `max-width`: `65ch` for body containers works with any font size.
 
 **All caps body text** - reserved for: labels, badges, category markers, short UI labels only. Never for sentences or paragraphs.
 
-**Inconsistent tracking** - only use `letter-spacing` intentionally. Positive tracking on uppercase labels is fine. Negative tracking on small body text reduces readability. Random tracking changes across components signal lack of system.
+**Inconsistent tracking** - only use `letter-spacing` intentionally. Positive tracking on uppercase labels is fine. Negative tracking on small body text reduces readability.
 
 ---
 
@@ -136,8 +165,8 @@ Enforce with `max-width`: `65ch` for body containers works with any font size.
 | Use case | letter-spacing |
 |---|---|
 | Body text | `0` (default) |
-| Uppercase labels / badges | `0.05em – 0.1em` |
-| Display headings | `−0.02em – 0.01em` |
+| Uppercase labels / badges | `0.05em - 0.1em` |
+| Display headings | `-0.02em - 0.01em` |
 | Monospace code | `0` or slight positive |
 
 ---
@@ -174,68 +203,19 @@ Test: Can you tell which element is a heading just from the weight/family, witho
 
 ## Brand Archetype Quick Guide
 
-Pick the archetype closest to the project brief; use the recommended pairing
-as a starting point (adjust for specific constraints).
-
 | Archetype | Character | Recommended Pairing |
 |-----------|-----------|---------------------|
 | SaaS / productivity | clear, neutral, utilitarian | Inter (UI) + Inter (body) - single family |
 | Consumer / editorial | warm, opinionated, expressive | Fraunces or GT Sectra (display) + Inter (body) |
 | Enterprise / finance | authoritative, conservative | IBM Plex Sans (UI) + IBM Plex Serif (body) |
 | Developer tools | technical, efficient | Geist (UI) + Geist Mono (code) |
-| Bold / expressive | high-energy, distinctive | Söhne or Mona Sans (display) + Inter (body) |
-
-**Selection heuristic:** If the brief uses words like "professional", "trustworthy", "clean" → SaaS or Enterprise. If "warm", "editorial", "narrative" → Consumer. If "bold", "energetic", "distinctive" → Bold. If "technical", "efficient", "fast" → Dev tools.
-
----
-
-## Variable Fonts
-
-Variable fonts expose typographic axes that can be animated or set per-context
-via `font-variation-settings`. Prefer variable fonts over static family fallbacks
-when available - one file covers all weights and widths.
-
-### Common axes
-
-| Axis | Range | Purpose |
-|------|-------|---------|
-| wght | 100–900 | Weight (Thin → Black) |
-| wdth | 50%–150% | Width (Condensed → Extended) |
-| ital | 0 / 1 | Italic toggle (discrete in most) |
-| opsz | font-size value | Optical size (auto-applies when `font-optical-sizing: auto`) |
-
-### @font-face format
-
-```css
-@font-face {
-  font-family: 'InterVariable';
-  src: url('/fonts/InterVariable.woff2') format('woff2-variations');
-  font-weight: 100 900;
-  font-style: normal;
-}
-```
-
-### Usage via font-variation-settings
-
-```css
-.heading { font-variation-settings: "wght" 700, "opsz" 32; }
-.body    { font-variation-settings: "wght" 400; }
-```
-
-### Fallback strategy
-
-Always include a non-variable fallback of the same family in the font stack:
-
-```css
-font-family: 'InterVariable', 'Inter', -apple-system, system-ui, sans-serif;
-```
+| Bold / expressive | high-energy, distinctive | Sohne or Mona Sans (display) + Inter (body) |
 
-**See:** [`./i18n.md`](./i18n.md) §Multi-Script Font Stacks for when a multi-script project should ship weighted-static fonts rather than a single variable font (some scripts ship as static-only families; mixing scripts in a single variable file is rarely viable).
+**Selection heuristic:** If the brief uses words like "professional", "trustworthy", "clean" use SaaS or Enterprise. If "warm", "editorial", "narrative" use Consumer. If "bold", "energetic", "distinctive" use Bold. If "technical", "efficient", "fast" use Dev tools.
 
 ---
 
 ## Micro-Typography
-Source: jakubkrehel/make-interfaces-feel-better (MIT) - typography.md
 
 ### text-wrap
 
@@ -254,7 +234,7 @@ Apply antialiasing at root level only:
   -moz-osx-font-smoothing: grayscale;
 }
 ```
-Never apply per-element - this creates inconsistency within a single text block and is one of the most common micro-typography mistakes. The antialiased value makes text appear slightly thinner/lighter, which is generally preferred for UI type at modern screen densities.
+Never apply per-element - this creates inconsistency within a single text block.
 
 ### Tabular numerals
 
@@ -262,52 +242,4 @@ Use tabular-nums on any surface where numbers change dynamically or need to alig
 ```css
 .counter, .price, .timer, .table-cell { font-variant-numeric: tabular-nums; }
 ```
-Proportional numerals (the default) cause text to shift width when numbers change, creating a distracting jitter in timers and prices. Exception: Inter's `1` character widens slightly with tabular-nums - test at your numeric composition before committing.
-
-## Font Pairings Catalog
-Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) - data/typography.csv
-
-57 professionally curated pairings grouped by use-case vertical. For font loading, see `reference/data/google-fonts.csv` for the full 1923-font reference.
-
-### SaaS / Productivity
-- **Inter + Inter** (mono weight hierarchy) - The "safe default" for app UIs. Use regular (400) for body, medium (500) for labels, semibold (600) for headings. Consistent x-height, excellent at small sizes.
-- **Inter + JetBrains Mono** - For dev tools and dashboards with code display. JetBrains Mono has excellent legibility at 12-14px.
-- **Geist Sans + Geist Mono** - Vercel's pair; clean, modern, designed together.
-- **Outfit + DM Mono** - Friendly SaaS feel with clear code fallback.
-
-### Consumer / Marketing
-- **Satoshi + Cabinet Grotesk** - High-energy, modern consumer feel.
-- **Plus Jakarta Sans + Syne** - Playful but legible; works for creative consumer apps.
-- **DM Sans + DM Serif Display** - Classic pairing; editorial headers, clean body.
-- **Nunito + Source Code Pro** - Approachable and friendly.
-
-### Finance / Enterprise
-- **IBM Plex Sans + IBM Plex Mono** - Authoritative, systematic, designed for data-heavy interfaces.
-- **Source Sans 3 + Source Code Pro** - Adobe's workhorse pair; widely trusted.
-- **Lato + Roboto Mono** - Clean, neutral enterprise pair.
-
-### Editorial / Publishing
-- **Playfair Display + Source Serif 4** - High contrast serif headers with readable body serif.
-- **Cormorant Garamond + Proza Libre** - Elegant luxury/editorial tone.
-- **Libre Baskerville + Libre Franklin** - Free-license editorial pair.
-- **EB Garamond + Lato** - Classic print feel with modern body.
-
-### Wellness / Health
-- **Nunito + Nunito Sans** - Soft, approachable, consistent x-height.
-- **Quicksand + Work Sans** - Rounded, friendly, healthcare-appropriate.
-- **Raleway + Open Sans** - Clean and welcoming.
-
-### Dev Tools
-- **JetBrains Mono + Inter** - Code-first, UI-second; natural for developer tools.
-- **Fira Code + Fira Sans** - Cohesive family; ligatures available.
-- **Cascadia Code + Segoe UI** - Microsoft's modern dev pair.
-
-### Luxury / Fashion
-- **Cormorant + Montserrat** - High contrast serif + geometric sans; classic luxury.
-- **Bodoni Moda + Jost** - Fashion editorial feel.
-- **Playfair Display + Raleway** - Elegant header + clean body.
-
-### Gaming / Entertainment
-- **Syne + DM Sans** - Bold, energetic headers; clean readable body.
-- **Bebas Neue + Open Sans** - Impact headlines; neutral body.
-- **Exo 2 + Roboto** - Futuristic but readable.
+Proportional numerals (the default) cause text to shift width when numbers change, creating jitter in timers and prices. Exception: Inter's `1` character widens slightly with tabular-nums - test at your numeric composition before committing.

package/reference/ux-writing.md

@@ -0,0 +1,60 @@
+# UX Writing - Domain Index
+
+This is the domain entry-point for UX writing. Load this file when the task
+involves voice, tone, or the copy standards that govern text a user reads in
+the product: button labels, error messages, empty states, onboarding copy, and
+microcopy. It does not cover the engineering side of localization (see
+`reference/responsive.md` for string expansion budgets and `Intl.*` APIs); it
+does not cover label position in forms or information architecture (see
+`reference/interaction.md`).
+
+---
+
+## Fragment Index
+
+→ **`reference/brand-voice.md`** (Phase 24) - use when establishing or
+auditing tone: 6 voice axes (Formal-Casual, Serious-Playful, etc.), 12
+archetypes, tone-by-context matrix, industry-context palettes
+
+→ **`reference/style-vocabulary.md`** (Phase 24) - use when confirming an
+aesthetic direction has a compatible voice register: the `Avoid For` column
+cross-checks brand fit; `Best For` confirms product-type alignment
+
+→ **`reference/anti-patterns.md`** - use when auditing existing copy: the
+BAN/SLOP grep patterns surface copy violations (AI-tells, filler phrases)
+alongside visual ones
+
+---
+
+## Rules of Thumb
+
+**1. Voice axes are independent from archetypes.**
+Pick a position on each of the 6 axes first (Formal-Casual, Serious-Playful,
+Authoritative-Supportive, and so on), then layer an archetype on top. The
+archetype does not determine the axis position - they are orthogonal dimensions
+in `reference/brand-voice.md`.
+
+**2. Never use placeholder text as the sole label for a form field.**
+It disappears on focus, fails WCAG 1.3.5, and collapses under translation.
+Top-aligned labels are the only position that absorbs localization expansion
+without breaking layout.
+
+**3. Error messages follow a three-clause structure: what happened, why, what
+to do.**
+State the event in past tense, explain the cause in one clause, give a present
+tense imperative for recovery. No tech jargon. Never blame the user.
+
+**4. Shift toward supportive tone during error, empty-state, and onboarding
+moments.**
+Even a formally-voiced product should move on the axis toward supportive when
+the user is at risk of abandonment. The per-context tone matrix in
+`reference/brand-voice.md` provides the exact adjustment.
+
+---
+
+## Cross-Domain See Also
+
+- String expansion budgets constrain copy length: `reference/responsive.md`
+- Error copy paired with form patterns: `reference/interaction.md`
+- Empty-state copy pairs with onboarding pattern: `reference/interaction.md`
+- Style direction voice register cross-check: `reference/style-vocabulary.md`

package/scripts/lib/manifest/schemas/skills.schema.json

@@ -24,7 +24,48 @@
         "properties": {
           "name": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "description": "Skill id = source/skills/<name>/ directory name."
+          },
+          "frontmatter_name": {
+            "type": "string",
+            "description": "Frontmatter name: value when it is not the default gdd-<name>."
+          },
+          "description": {
+            "type": "string",
+            "minLength": 20,
+            "maxLength": 1024,
+            "description": "Skill description (Phase 28.5 budget: 20..1024 chars)."
+          },
+          "argument_hint": {
+            "type": "string"
+          },
+          "tools": {
+            "type": "string",
+            "description": "Comma-separated allow-list emitted as the frontmatter tools: line."
+          },
+          "user_invocable": {
+            "type": "boolean"
+          },
+          "disable_model_invocation": {
+            "type": "boolean"
+          },
+          "registered_in_phase": {
+            "type": "string"
+          },
+          "aliases": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Reserved for pin shortcuts; honored by the pin metadata catalogue."
+          },
+          "extra_frontmatter": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Non-managed frontmatter lines preserved verbatim (color, model, writes:, ...)."
           }
         }
       }