docs(frontend): add numeric reuse governance

[Tinycute00]

Summary

• Add numeric reuse governance to the frontend skill router so UI work routes through explicit token/component/variant budgets.
• Extend the design router with surface-label selection, DESIGN.md budget checks, imagegen-to-code budget reconciliation, and QA checklist coverage.
• Expand the DESIGN.md architecture contract with a Section 5 reuse budget ledger and reviewer checklist for tokens, variants, icons, buttons, forms, cards, layouts, spacing, radius, and shadow.

Verification

• RED contract captured before docs changes: .omo/evidence/frontend-numeric-reuse-budget/red-doc-contract.txt
• GREEN docs contract: exit=0, numeric reuse governance contract present
• Skill routing contract: exit=0, frontend skill routes to enforceable numeric reuse governance
• Path integrity: exit=0, frontend governance docs paths readable
• Encoding hygiene: exit=0, utf-8 clean; no BOM/mojibake markers
• Diff hygiene: git diff --check clean for the three edited files

Notes

These numeric thresholds are written as conservative agent-governance defaults. The docs distinguish externally backed design-system limits from pragmatic local controls so reviewers can tune the exact numbers without losing the enforceable workflow.

---

Summary by cubic

Adds numeric reuse governance and expressive-surface intent to frontend docs and routing so UI stays within clear budgets while allowing intentional campaign/marketing expression. Also syncs the builtin frontend skill metadata to advertise these rules.

• New Features

  • Frontend skill router enforces numeric reuse budgets, surface-label routing, and expressive-surface governance (operational/commercial/campaign/translation).
  • Design router requires a DESIGN.md reuse budget ledger, adds surface intent selection, reconciles imagegen to existing tokens/components, and checks that expressive layers sit outside reusable budgets.
  • design-system-architecture.md: Section 1 adds an Aesthetic Intent Brief; Section 5 formalizes the reuse budget table and reviewer checklist; motion/depth QA now ties back to intent.
  • Synced builtin frontend skill description in skills-loader-core to reflect numeric reuse governance and expressive intent.

• Migration

  • Update DESIGN.md: add the Section 5 reuse budget ledger, choose a surface label and intent, and complete the Aesthetic Intent Brief before coding.
  • Count variants/primitives before code; expand budgets with rationale in DESIGN.md before exceeding; collapse imagegen output into existing tokens/components.

^{Written for commit 9c9d484. Summary will update on new commits.}

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[Tinycute00]

I have read the CLA Document and I hereby sign the CLA

[Tinycute00]

Subagent observation QA

Ran three independent read-only QA agents against this PR branch to observe whether the new frontend governance docs actually steer agents toward reusable design-system primitives.

Scenario 1: same DESIGN.md, same billing screen, two independent agents

Fixture: product-app surface with existing primitives Button(primary/secondary/danger), Card(panel/metric), Field(text/select/search), Toolbar, DataTable, StatusPill, MetricTile, EmptyState, Lucide-only icons, and bounded radius/shadow/layout budgets.

Both agents converged on the same core result:

• Reuse Button(primary) for upgrade CTA.
• Reuse Button(secondary) for neutral payment/invoice actions.
• Reuse Button(danger) for cancellation/destructive action.
• Reuse Card(panel) for plan/payment/invoices/danger-zone containers.
• Reuse Card(metric) / MetricTile for compact billing facts.
• Reuse Field, Toolbar, DataTable, StatusPill, and EmptyState.
• Add no new primitive.
• Request no budget expansion.

Observed effect: the docs were clear enough for separate agents to avoid PaymentMethodCard, DangerZoneCard, a new button style, or a second icon family.

Scenario 2: repeated change requests on one dashboard

Fixture: dashboard surface with existing Button, Card(panel/metric/alert), Field, Toolbar, EmptyState, MetricTile, DataTable, StatusPill, and FilterBar.

Sequential requests tested:

1. Build operations dashboard with KPI cards, incident table, owner filter, empty state.
2. Add bulk resolve and dangerous delete selected actions.
3. Add highlighted urgent SLA card.
4. Add compact filter row with search, owner, status, date range.

Agent result:

• Reused MetricTile / Card(metric), DataTable, FilterBar, Field, EmptyState, and Toolbar for the initial dashboard.
• Reused existing Button(primary|secondary) and Button(danger) for bulk actions.
• Reused Card(alert) / status tokens for urgent SLA instead of inventing a fourth card shell.
• Reused FilterBar and one field shell for compact filters.
• Requested no budget expansion.

Observed effect: repeated changes stayed inside component/variant budgets; the docs pushed consolidation instead of one-off variants.

Ambiguities found and addressed

The agents found two practical ambiguity points:

• A project DESIGN.md may use project-local variant names like panel, metric, or alert, while the architecture table examples mention default names like elevated/filled/outlined.
• A new input behavior such as date range could be unclear: is it a new form primitive group or an input type inside the existing field shell?

Follow-up commit 6ce7996d8 addresses both:

• Project-local variant names are authoritative; compare count, behavior, and semantic fit instead of literal example names.
• New input types inside the same field shell do not require a new primitive unless they introduce distinct composite behavior such as a calendar popover or date-range picker.

Verification after follow-up

• git diff --check clean for the follow-up doc patch.
• Governance contract check passed, including the two ambiguity fixes.
• Encoding check passed: UTF-8 clean, no BOM/mojibake markers.

[Tinycute00]

Research-backed expressive surface governance follow-up

Added commit 0648300c4 to address the design concern that numeric reuse governance can protect baseline consistency but can also create generic/AI-looking UI if applied uniformly to every surface.

Plan applied

1. Keep numeric reuse governance for reusable interaction primitives: buttons, forms, cards, icons, navigation, data displays, color/radius/shadow/spacing tokens.
2. Add a surface-intent layer before component budgeting, so different UI goals get different governance strength.
3. Add an aesthetic intent brief to DESIGN.md, forcing the agent to name the emotional target and visible design idea before implementation.
4. Allow bespoke visual layers for expressive surfaces without turning every visual flourish into a reusable component.
5. Preserve accessibility and reduced-motion requirements for 3D, parallax, scroll-linked, and shader-like effects.

New concepts landed

• operational: product app, dashboard, settings, forms, data tables. Strict reuse-first governance.
• commercial: marketing, landing, pricing, commerce. Balanced governance; allows bespoke hero/section/motion layers while controls remain reusable.
• campaign: launch pages, ads, brand stories, brandkit/image-only. Expressive first; only repeated controls and interaction primitives enter component budgets.
• translation: image-to-code/mockup-to-implementation. Explore visually first, then collapse repeated interaction pieces back into DESIGN.md.

DESIGN.md now requires an Aesthetic Intent Brief

For non-trivial visual surfaces, the agent must declare:

• surface intent
• target emotion
• signature visual idea
• attention path for the first 3 seconds
• motion role
• bespoke visual layer
• reusable primitive boundary

This turns subjective user intent into observable QA targets instead of letting the model default to generic consistency.

Research anchors

• DTCG Design Tokens Format 2025.10: design tokens express design decisions across disciplines, tools, and technologies, and support a shared source of truth across design/development workflows. https://www.designtokens.org/TR/2025.10/format/
• W3C/DTCG stable announcement: stable token spec supports theming, aliases, component-level references, and cross-platform consistency. https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/
• USWDS design tokens: token palettes constrain broad CSS value choices to improve design efficiency and designer/developer communication. https://designsystem.digital.gov/design-tokens/
• USWDS theme color tokens: official role-based color families support the existing color-budget direction. https://designsystem.digital.gov/design-tokens/color/theme-tokens/
• Carbon spacing: official 2/4/8-derived spacing scale supports tokenized spacing budgets. https://carbondesignsystem.com/elements/spacing/overview/
• Carbon component tokens/states: component-specific tokens and interaction-state tokens support component-scoped governance. https://carbondesignsystem.com/elements/color/overview/
• Figma variants: variants group similar components and reduce guesswork; Figma does not recommend using variants to group different icons. https://help.figma.com/hc/en-us/articles/360056440594-Create-and-use-variants
• Material 3 theming: color, typography, and shapes are theme subsystems; component theming is flexible but flows through the theme. https://developer.android.com/develop/ui/compose/designsystems/material3
• WCAG 2.2: accessibility uses testable success criteria and remains necessary for web content. https://www.w3.org/TR/WCAG22/
• USWDS accessibility process: accessible components should be tested with keyboard, screen readers, zoom, touch, automated tools, manual audits, and ongoing feedback. https://designsystem.digital.gov/documentation/accessibility/

Verification

• git diff --check clean for all three touched docs.
• Expressive governance contract passed: required routing/intent/brief terms are present.
• Encoding check passed: UTF-8 clean, no BOM/mojibake markers.