Ant Design UI Story Adoption Analysis

• Date: 2026-06-09 (addendum 2026-06-12: "Agent Infrastructure Strategy" section added)
• Status: Research report. No product code changed.
• Scope: How FS.Skia.UI can make heavy use of Ant Design's design principles, visual choices, token model, enterprise patterns, and agent-facing guidance without taking a React or DOM dependency. Updated decision: Ant Design's color/contrast choices should be selectable as a design-system policy that can replace the current WCAG-only gate for generated-template validation.
• Primary external source: https://ant.design/docs/spec/introduce/?theme=light
• Ant Design docs version observed during research: 6.4.3.

Executive Summary

Ant Design should be adopted here as a design language, token taxonomy, pattern library, and quality bar. It should not be adopted as a direct React component dependency. FS.Skia.UI renders through Skia and F# control IR, so the practical path is to translate Ant's stable ideas into local primitives:

• A richer semantic token layer generated from the existing DTCG source, with Ant-style seed, map, alias, and component-token groups.
• A design-system color/contrast policy selector. The current WCAG gate becomes the wcag policy; Ant Design becomes the first alternative policy; later policies can add Material, Fluent/Fluid, or other systems without changing the template UX.
• A central visual-state style resolver that maps ControlKind, VisualState, intent, validation state, and theme into concrete draw styles.
• A controls story that emphasizes enterprise workflows: list pages, dense data grids, forms, validation, inline editing, feedback, overlays, navigation, dashboards, empty states, and evidence captures.
• Local agent guidance under .agents/skills/fs-skia-ant-design/SKILL.md, mirrored to .claude by the existing generated-skill machinery, so Codex and Claude follow the same Ant-inspired rules.

The revised design decision is that the repo should no longer hard-code one universal color/contrast authority. Instead, validation should be policy-driven: wcag preserves today's explicit ratio gate, ant validates Ant Design's own semantic color and contrast choices, and future policies such as material or fluent can plug into the same mechanism. Ant's default brand blue is #1677ff, but the point is broader than one color: selecting the Ant policy should select the Ant token palette, neutral transparency model, functional colors, text/background contrast expectations, and restrained enterprise color usage.

Design Decision: Policy-Selected Color And Contrast

The design-system policy should become a template parameter and a governance input, not a fixed assumption baked into ContrastCheck.

Proposed template surface:

dotnet new fs-skia-ui --design-system wcag
dotnet new fs-skia-ui --design-system ant

wcag should be the compatibility default at first because it preserves current generated-product behavior. ant should be the first richer design-system alternative. Future values can include material, fluent, or fluid depending on the naming decision for the next design language.

The conceptual gate should become DesignSystemColorCheck or ColorPolicyCheck. It may keep the existing ContrastCheck target name for backward compatibility, but internally it should delegate to a selected policy:

type DesignSystemPolicy =
    | Wcag
    | Ant
    | Material
    | Fluent
    | Custom of string

type ColorPolicy =
    { Id: DesignSystemPolicy
      TokenSeed: string
      Pairings: ValidatedPairing list
      ThresholdFor: Role -> float
      ReportLabel: string }

The policy controls both token selection and validation semantics. The template parameter should not merely switch colors while leaving the WCAG-only gate in place; that would make Ant a paint preset rather than a design-system choice. For Ant, the policy should encode Ant Design's choices: colorPrimary #1677ff, functional color families such as success, warning, error, and info, neutral text and surface roles, default typography of 14/22, body/title contrast expectations, and semantic pairings for text, controls, feedback, selection, and navigation.

This gives follow-up work a clean extension seam:

This also changes the report's earlier recommendation: Ant colors should not just be "certified by the local WCAG gate." For the Ant option, Ant's policy is the selected authority. A WCAG-derived measurement can remain useful implementation machinery, but the user-facing contract is "this generated product follows the Ant Design policy."

Research Basis

The relevant Ant Design source material breaks into five groups.

Development-side sources are also useful, even though this project is not a React renderer:

What Ant Design Is Really Offering

Ant's value is not just a palette or a catalog of widgets. The durable ideas are:

The strongest match for this repository is an "Ant-inspired Skia enterprise UI kit": locally rendered, locally tokenized, and locally governed, but borrowing Ant's vocabulary and decision rules.

Local Machinery Today

The repository already has several pieces that make this feasible.

The current design-token set is intentionally small: foreground, background, accent, danger, muted, font family, font size, density, corner radius, and contrast ratio for light and dark. Ant's theme model is much broader. The adoption path should therefore start with an additive semantic layer rather than immediately changing the public Theme record.

Target Design Story

The UI story should become:

FS.Skia.UI.Controls provides a deterministic, Skia-rendered, F#-native enterprise interface system. It uses typed controls, generated DTCG design tokens, policy-selected color/contrast validation, and Ant-inspired interaction patterns to produce clear, dense, consistent operational UIs.

That story can be expressed in four user-visible ways:

Visual System Adoption

1. Token Taxonomy

Ant's customize-theme docs describe a three-layer token lifecycle:

• Seed tokens: design intent roots, such as primary color, base background, base text, font size, border radius, and control height.
• Map tokens: derived gradients and state-specific values, such as primary hover, primary active, error background, container background, border, fill, and text variants.
• Alias tokens: common semantic aliases used across components, such as link color, elevated background, split border, selected item background, and text secondary.

FS.Skia.UI should mirror that structure in DTCG, but adapt the names to F# and Skia rendering. A plausible local taxonomy:

Important migration rule: adding public token names under DesignTokens.fsi is a contract change and must route through the repo's public-surface gates. Until then, an internal generated module or an additive namespace can absorb the experiment.

2. Color Choices

Ant's color docs define a system-level palette and product-level semantics: brand color, functional colors, neutral text/background/border/separator roles, and restrained enterprise usage. Ant's default brand color is #1677ff. Functional defaults include success green, warning gold, and error red families.

Policy-specific recommendation:

Ant's font docs target high contrast for body/title text. This repo currently uses contrastRequiredRatio = 4.5 in shipped tokens. That remains the wcag policy's compatibility contract. For ant, the right move is to encode Ant's body/title, neutral, functional, and primary pairings as the selected policy. The checker can still report ratios, but it should not reject Ant solely because Ant's chosen policy differs from the existing WCAG-only gate.

3. Typography

Ant's typography story is practical and compatible with this repo:

4. Layout And Density

Ant uses an 8-unit layout grid and a 24-column raster for page layout. Ant's React token model also exposes controlHeight = 32, sizeUnit = 4, and sizeStep = 4.

Local adaptation:

5. Elevation, Overlays, And Shadow

Ant's shadow docs define height levels for grounded controls, hover/floating states, dropdowns, and dialogs. FS.Skia.UI can translate this into local elevation tokens:

Do not implement shadow as decoration first. Implement it where it communicates layering: overlay, menu, dialog, popover, drawer, fixed headers.

6. Icons

Ant's icon docs emphasize clear meaning, consistent style, flat perspective, consistent stroke/rounding, and color matching surrounding text except for state icons.

Local adaptation:

• The icon and icon-button controls should distinguish system icons from business/illustrative icons.
• Icon-only buttons need accessible names and tooltip/invitation behavior.
• State icons should use semantic status tokens, not arbitrary accent colors.
• A future icon import pipeline could consume Ant Design Icons metadata or SVG paths, but it should be converted into local path primitives rather than shipping a web icon dependency.

7. Motion

Ant's motion docs emphasize Natural, Performant, and Concise. That aligns with this repo's deterministic evidence mode and control-preview obligations.

Local rule:

• Animate only state transitions that explain cause and effect: hover, press, selection, loading, insertion/removal, validation, overlay enter/exit.
• Keep transitions short. Generated evidence must be able to capture stable states deterministically.
• Add motion tokens only after render timing and evidence captures can verify them without flake.

Interaction Pattern Adoption

Ant's interaction principles map cleanly to the existing VisualState and pointer/keyboard model.

The local VisualState union already names Normal, Disabled, Hover, Pressed, Focused, Selected, Loading, and Validation. The missing piece is a central resolver that turns these states into consistent draw styles across all controls.

Proposed resolver shape:

type ControlIntent =
    | Default
    | Primary
    | Success
    | Warning
    | Danger
    | Link
    | Text

type ControlStyle =
    { Text: Color
      Background: Color
      Border: Color
      FocusRing: Color option
      Shadow: string option
      FontSize: float
      Radius: float }

val resolve:
    theme: Theme ->
    kind: ControlKind ->
    intent: ControlIntent ->
    states: VisualState list ->
    ControlStyle

The exact types should follow existing code style, but the key idea is stable: control rendering should consume semantic roles and states, not sprinkle theme.Accent, theme.Muted, and theme.Danger directly across render code.

Component And Page Pattern Adoption

Buttons And Commands

Ant button guidance gives specific rules that are worth importing:

• Default buttons are safe non-primary actions.
• Primary buttons are for completion or recommended actions, with at most one primary button per group.
• Text buttons are for low-emphasis actions, especially in tables.
• Icon-only buttons need tooltips.
• Dashed buttons guide "add content" actions.
• Danger buttons mark destructive operations.
• Labels should be concise verbs and describe the action result.

Local implications:

• ButtonIntent.Primary, ButtonIntent.Secondary, and ButtonIntent.Danger should render through the style resolver. If an intent is lowered into attrs but not consumed by the renderer, that is a fidelity gap.
• Add or document Default, Text, Link, and Additive/Dashed button modes only when the control API can express them consistently.
• Table row actions should default to low-emphasis text/icon buttons, with destructive actions gated by popconfirm/undo patterns.

Forms And Data Entry

Ant data-entry and form-page docs emphasize clear labels, contextual help, structured formats, good defaults, immediate feedback, task decomposition, and security/recovery actions.

Local priorities:

This points to a future Form, FormItem, FieldHelp, and ValidationSummary story, even if the initial implementation is docs/templates rather than new controls.

Data Display

Ant data-display guidance is especially relevant to DataGrid, ListView, and charts:

• Organize by information importance, operation frequency, and association.
• Design extreme states: long text, empty content, loading content.
• Tables are efficient for structured comparison and often pair with sort, search, filter, and paging.
• Empty table cells should use a clear placeholder, not appear broken.
• Cards are useful for lighter, personalized information blocks, but should be limited by grid and spacing discipline.

Local priorities:

Navigation

Ant navigation guidance maps to the showcase shell:

• Side navigation is suited to multi-level, operation-intensive dashboard apps.
• Breadcrumbs should be used sparingly and kept shallow.
• Tabs switch large information areas without page transitions.
• Steps guide predefined workflows.
• Pagination helps users understand large content sets and remaining work.

Local priorities:

• Keep the current left navigation rail as the primary showcase/navigation pattern.
• Add tabs for local subviews, not whole-app navigation unless the page scope is limited.
• Add steps for form wizard examples.
• Add pagination for data-grid/list examples instead of relying only on scroll.

Feedback

Ant feedback guidance is a direct checklist for this repo:

The existing showcase page 08-overlays-and-feedback.md is the natural place to make this concrete.

Page Templates For Generated Apps

Ant's research template docs are useful raw material for generated-product followups:

This gives the UI story a stronger product feel than a pure controls gallery. The gallery can still be the evidence vehicle; generated apps can be the consumer story.

Governance And Gate Impact

Adopting Ant Design deeply will touch governed surfaces. Route decisions should be expected, not worked around.

The existing .agents to .claude skill synchronization is important: the canonical Ant skill should be .agents/skills/fs-skia-ant-design/SKILL.md. The .claude tree should be regenerated by the established skill-tree generator and verified by the skill sync/guidance gates. Do not hand-sync those trees.

Agent Infrastructure Strategy

Added 2026-06-12. Ant Design is a large, information-dense, durable knowledge area. This section answers a practical question the rest of the report assumes but does not state: how should the repo's agent infrastructure (skills, reference data, subagents, workflows, memory, gates) be used to incorporate it? The decision rule is not "how big is the topic" but:

Match the mechanism to the lifetime and reuse of the artifact. Durable, reused-every-feature knowledge belongs in skills + reference data. One-time or iterative acquisition/transformation belongs in subagents/workflows. Tiny decisions belong in memory. Enforcement belongs in gates over a single source.

Mechanism selection

Layered architecture (not "just skills")

1. Knowledge layer = a thin skill family + fat reference files. Do not pour Ant Design into one mega-skill; skills load into agent context and a 50KB skill is a tax on every task. Use the repo's existing thin-skill-over-single-source pattern (fs-skia-design-tokens already points at design-tokens.tokens.json). Refinement of the "Draft Local Skill" above: keep fs-skia-ant-design as the procedural front door (scope, source priority, translation rules, checks), and move the dense content into reference data files it points to:

   • docs/reference/ant-design/color-system.md (+ a token data file) — seed/map/alias taxonomy and the palette derivation.

   • docs/reference/ant-design/principles.md — values, spacing, motion, elevation, icon, density tables.

   • docs/reference/ant-design/patterns.md — per-component and per-page recipes. Optionally split a second focused skill (fs-skia-ant-color vs fs-skia-ant-patterns) only if the single skill's front door grows past a screen.

2. Acquisition/maintenance layer = subagents + workflows (ephemeral). The skills are the output; agents are how it is produced and kept current. The official feeds this report already lists are the inputs: the Ant MCP server (antd mcp) and llms-full.txt/llms-semantic.md are ideal subagent fuel because an isolated context window can digest them without polluting the main thread. Use deep-research for the color algorithm and contrast tables; use a Workflow for batch token generation/verify and for control/page audits.

3. Enforcement = the token single source + gates. Make Ant tokens generated from the seed via the palette algorithm, never hand-copied, so they cannot drift and always pass the selected color policy. This is the DesignTokenGen + DesignTokenDrift + policy-backed color-check path the report already describes.

4. Process = treat adoption as a Spec Kit feature/constitution change, run through specify -> plan -> tasks -> implement, so the skill family, reference files, policy plumbing, and gate wiring are designed and evidenced like any feature (and the skill sync into .claude is owned by the generator, never hand-maintained).

Spec Kit Design Stage Decision

UI and design-system work should add an optional design stage between specify and plan:

specify -> design -> plan -> tasks -> implement

The stage should be named speckit-design. It is required for features that change visual language, design tokens, interaction states, showcase stories, generated templates, page patterns, or Penpot assets. It should be skipped for routine framework-internal changes where there is no user-facing design decision.

The boundary is deliberate:

• specify captures the user outcome, constraints, non-goals, and acceptance criteria without prematurely choosing token names or page structure.
• speckit-design translates that outcome into concrete design artifacts: token taxonomy, selected design-system policy, interaction states, layout and density rules, Penpot import/export notes, and required visual evidence.
• plan consumes those artifacts to decide public surface impact, renderer work, template impact, gates, and evidence paths.
• tasks and implement then build against the planned contracts.

Running design after plan would make the plan guess at public token shape, style-resolver boundaries, template parameters, and evidence needs. That is too late for governed UI work because those decisions affect .fsi surfaces, generated baselines, contrast policy, screenshots, and Route escalation.

Recommended design-stage artifacts:

Penpot Integration Boundary

Penpot should be an authoring, inspection, and collaboration workspace, not the canonical product source. The canonical source stays in the repository:

src/Controls/design-tokens.tokens.json
  -> DesignTokenGen
  -> src/Controls/DesignTokens.fs
  -> DesignTokenDrift / color-policy gates

The design workflow may load a feature or design-system library into Penpot by exporting the repo's DTCG token document and any feature-specific mockup assets. Changes that matter to the product must return as reviewed DTCG/source diffs, then flow through RefreshSurfaceBaselines, DesignTokenDrift, the selected color-policy gate, and whatever additional gates Route prints. Do not treat a Penpot project file, manual color swatch, or remote Penpot state as a second source of truth.

This keeps the useful part of Penpot -- visual inspection, shared design review, and prototype composition -- without weakening the repo's deterministic generation and drift-check model.

FS.Skia.UI Token Libraries For Penpot

Penpot should receive FS.Skia.UI-specific token libraries, not raw Ant Design libraries. Ant remains the upstream design language and token inspiration; the exported libraries must encode the local renderer roles, local naming, and local governance model.

Recommended library set:

The Ant library should be generated or curated from Ant seed, functional, neutral, semantic, and component-token concepts, but it must not import Ant React components, CSS variables, Less variables, DOM structure, or runtime dependencies. The useful translation path is:

Ant docs / Ant MCP
  -> fs-skia-ant-design skill + reference data
  -> FS.Skia.UI DTCG token library
  -> generated F# tokens + gates
  -> optional Penpot import for design review

Highest-leverage single artifact

Reimplement Ant's @ant-design/colors generate(seed) (a 10-shade palette derived from one seed via HSV hue/saturation/brightness curves, plus the dark-mode blend) as a pure F# function feeding the DTCG generator. Ant's three-tier seed -> map -> alias model maps exactly onto DTCG and the local token pipeline, so this one function yields Ant-correct, drift-checked, contrast-gated palettes for any brand color. Everything else (principles, per-component parity, generated profiles) layers on top of it. The MIT license on Ant's color package makes reimplementation (with attribution) clean.

Anti-patterns to avoid

• Dumping Ant prose into skills (context bloat; the durable unit is the algorithm + the single-source data, with the skill as a thin front door).
• Hand-maintaining bulk reference content that an agent could regenerate from the MCP/LLM feeds.
• Using ad-hoc subagents to produce knowledge and then never writing it into a durable skill/reference/token file (ephemeral work that evaporates).
• Hand-syncing .agents and .claude (let the generator own the mirror).

Recommended Roadmap

Phase 0 - Research And Decision Record

Done by this report:

• Capture official sources.
• Identify local machinery.
• Define the adoption direction and risks.
• Draft a local skill.

Phase 1 - UI Story Refresh

Low implementation risk, high clarity:

• Update showcase specs to explicitly say "Ant-inspired enterprise controls story".
• Document the design-system selector as the governing color/contrast decision: wcag remains the default, ant becomes the first alternative, and future values can add Material or Fluent/Fluid policies.
• Replace palette-only language with semantic roles: primary, success, warning, error, info, text, secondary text, disabled text, border, separator, container, elevated, selected, hover, focus.
• Add page-pattern examples: list page, form page, feedback page, workbench.
• Add a source index in the docs so future agents do not rediscover the same Ant pages.

Phase 2 - Token Model Design

Design before code:

• Write a token taxonomy doc mapping Ant Seed/Map/Alias/Component tokens to DTCG groups and generated F# names.
• Decide whether the first implementation is explicit DTCG values/aliases or a generator-side derivation algorithm.
• Introduce DesignSystemPolicy/ColorPolicy plumbing: wcag delegates to today's pairings, ant owns Ant semantic pairings, and later providers add Material/Fluent equivalents.
• Define policy-specific pairings before shipping status/selection/focus text roles.
• Decide which tokens are public and which remain internal.

Phase 3 - Style Resolver

Implementation focus:

• Add a central resolver for kind + intent + visual state + theme.
• Migrate buttons, text inputs, list rows, tabs, menus, and data-grid states first. These make the largest visual difference.
• Add tests proving selected, hover, pressed, focused, disabled, loading, and validation states resolve to intended roles.
• Keep old theme fields working.

Phase 4 - Component Pattern Parity

Broaden components where Ant adds real product value:

• Buttons: default, primary, text/link, danger, add/dashed, icon-only tooltip.
• Forms: form item, help text, validation summary, grouped/step form patterns.
• Data: table toolbar, sort/filter/pagination/empty states.
• Feedback: alert, notification, popconfirm, message/toast, dialog severity.
• Navigation: side menu, tabs, steps, pagination.

Phase 5 - Generated Product Story

Use Ant page templates as the consumer-facing demonstration:

• dotnet new fs-skia-ui --profile workbench
• --profile list-page
• --profile form-page
• --profile dashboard
• --profile operations

Even if these profiles are not implemented immediately, designing the showcase around those profiles will make the project feel like a coherent UI system.

Key Risks And Decisions

Draft Local Skill

This is a proposed skill, not an installed file. If adopted, place it at .agents/skills/fs-skia-ant-design/SKILL.md, regenerate the .claude mirror through the existing surface-baseline workflow, and let Route select the gates.

---
name: fs-skia-ant-design
description: Use when designing, documenting, or implementing FS.Skia.UI controls, showcase pages, generated app templates, design tokens, visual states, or local agent guidance that should follow Ant Design enterprise UI principles without introducing a React/DOM dependency.
compatibility: FS.Skia.UI.Controls + DTCG token pipeline + Skia renderer + generated skill sync; source references are Ant Design 6.x docs.
metadata:
  author: fs-skia-ui
  sources:
    - https://ant.design/docs/spec/introduce/
    - https://ant.design/docs/spec/values/
    - https://ant.design/docs/react/customize-theme/
---

# fs-skia-ant-design

## Scope

Use this skill for Ant-inspired UI story, control behavior, design-token,
theme, showcase, generated-template, color/contrast policy, and docs work in
FS.Skia.UI.

Do not use this skill to import Ant Design React components, CSS classes,
Less variables, DOM structure, or runtime dependencies into the Skia/F# product.
Do not treat the current WCAG gate as the only acceptable color/contrast
authority. Generated templates should select a design-system policy such as
`wcag` or `ant`.

## Source Priority

1. Official Ant Design spec docs:
   - Introduction: https://ant.design/docs/spec/introduce/
   - Values: https://ant.design/docs/spec/values/
   - Colors: https://ant.design/docs/spec/colors/
   - Font: https://ant.design/docs/spec/font/
   - Layout: https://ant.design/docs/spec/layout/
   - Dark mode: https://ant.design/docs/spec/dark/
   - Shadow: https://ant.design/docs/spec/shadow/
   - Icons: https://ant.design/docs/spec/icon/
   - Motion: https://ant.design/docs/spec/motion/
2. Official Ant pattern docs:
   - Design pattern overview: https://ant.design/docs/spec/overview/
   - Data entry: https://ant.design/docs/spec/data-entry/
   - Data display: https://ant.design/docs/spec/data-display/
   - Feedback: https://ant.design/docs/spec/feedback/
   - Navigation: https://ant.design/docs/spec/navigation/
   - Button: https://ant.design/docs/spec/buttons/
   - Direct manipulation: https://ant.design/docs/spec/direct/
   - Stay on page: https://ant.design/docs/spec/stay/
   - Lightweight interaction: https://ant.design/docs/spec/lightweight/
   - Invitations: https://ant.design/docs/spec/invitation/
   - Transitions: https://ant.design/docs/spec/transition/
   - Immediate reaction: https://ant.design/docs/spec/reaction/
3. Official development docs when token/component detail is needed:
   - Theme tokens: https://ant.design/docs/react/customize-theme/
   - CSS variables: https://ant.design/docs/react/css-variables/
   - CLI: https://ant.design/docs/react/cli/
   - MCP: https://ant.design/docs/react/mcp/
   - LLM files: https://ant.design/docs/react/llms/

## Workflow

1. Classify the task: token, style resolver, control, page pattern, showcase,
   generated template, docs, or skill guidance.
2. Read the smallest relevant Ant source page before making design claims.
3. Translate Ant concepts into local FS.Skia.UI primitives:
   - Ant tokens -> DTCG source and generated F# token modules.
   - Ant component states -> `VisualState` and a local style resolver.
   - Ant components -> local typed controls and Skia draw styles.
   - Ant page templates -> showcase specs and generated app profiles.
   - Ant feedback patterns -> local overlay/toast/dialog/validation controls.
   - Ant color and contrast choices -> selected `ant` policy pairings, not
     WCAG-only certification.
4. Preserve local governance:
   - Edit `src/Controls/design-tokens.tokens.json` for token values.
   - Regenerate generated surfaces instead of hand-editing them.
   - Run `./fake.sh build -t Route` before validation.
   - Run only the gates that `Route` prints.
5. For colors, identify the selected design-system policy:
   - `wcag`: use today's contrast pairings and thresholds.
   - `ant`: use Ant seed, functional, neutral, body/title, and semantic pairing
     expectations as the authority; ratios can be diagnostic.
   - future policies: add Material, Fluent/Fluid, or project-specific providers
     through the same policy interface.

## Mapping Rules

- Natural: every interaction has visible cause/effect.
- Certain: use common components, stable layout, generated tokens, and reusable
  patterns rather than per-page visual invention.
- Meaningful: avoid decorative UI; each control should support a task.
- Growing: use empty states, invitations, progressive disclosure, and helpful
  defaults to reveal capability over time.
- Keep color restrained: primary actions, information hierarchy, operation
  status, and feedback can use color; neutral surfaces carry most of the UI.
- Prefer stay-on-page patterns: inline edit, undo toast, popconfirm, drawer,
  inlay, tabs, and step flows before full navigation or modal interruption.

## Checks

- Docs-only: run `Route`; obey printed gates.
- Token value/name change: expect `RefreshSurfaceBaselines`,
  `DesignTokenDrift`, policy-backed color checks, and public-surface gates if
  routed.
- Template policy change: expect `TemplateCheck` and generated-product checks if
  routed.
- Renderer/style change: add focused rendering and interaction tests for visual
  states touched.
- Skill change: regenerate/check `.claude` mirrors through existing generated
  guidance gates.

## Useful Local Anchors

- `src/Controls/design-tokens.tokens.json`
- `src/Controls/DesignTokens.fs`
- `src/Controls/Theme.fs`
- `src/Controls/Types.fsi`
- `src/Color/Contrast.fsi`
- `src/Color/Palettes.fsi`
- `build/Governance/ContrastGate.fs`
- `docs/testSpecs/Showcase/00-controls-gallery-overview.md`

Useful Resources For Later

Ant Design Core

• Introduction: https://ant.design/docs/spec/introduce/
• Design Values: https://ant.design/docs/spec/values/
• Cases: https://ant.design/docs/spec/cases/
• Component overview: https://ant.design/components/overview/
• GitHub repository: https://github.com/ant-design/ant-design

Visual System

• Colors: https://ant.design/docs/spec/colors/
• Dark Mode: https://ant.design/docs/spec/dark/
• Font: https://ant.design/docs/spec/font/
• Layout: https://ant.design/docs/spec/layout/
• Shadow: https://ant.design/docs/spec/shadow/
• Icons: https://ant.design/docs/spec/icon/
• Motion: https://ant.design/docs/spec/motion/
• Ant Motion: https://motion.ant.design/
• Theme Editor: https://ant.design/theme-editor

Pattern Pages

• Design Patterns overview: https://ant.design/docs/spec/overview/
• Data Entry: https://ant.design/docs/spec/data-entry/
• Data Display: https://ant.design/docs/spec/data-display/
• Feedback: https://ant.design/docs/spec/feedback/
• Navigation: https://ant.design/docs/spec/navigation/
• Button: https://ant.design/docs/spec/buttons/
• Form Page: https://ant.design/docs/spec/research-form/
• List Page: https://ant.design/docs/spec/research-list/
• Workbench: https://ant.design/docs/spec/research-workbench/
• Result Page: https://ant.design/docs/spec/research-result/
• Exception Page: https://ant.design/docs/spec/research-exception/

Interaction Principles

• Make it Direct: https://ant.design/docs/spec/direct/
• Stay on the Page: https://ant.design/docs/spec/stay/
• Keep it Lightweight: https://ant.design/docs/spec/lightweight/
• Provide an Invitation: https://ant.design/docs/spec/invitation/
• Use Transition: https://ant.design/docs/spec/transition/
• React Immediately: https://ant.design/docs/spec/reaction/
• Proximity: https://ant.design/docs/spec/proximity/
• Alignment: https://ant.design/docs/spec/alignment/
• Contrast: https://ant.design/docs/spec/contrast/
• Repetition: https://ant.design/docs/spec/repetition/

Development And Agent Resources

• Customize Theme: https://ant.design/docs/react/customize-theme/
• CSS Variables: https://ant.design/docs/react/css-variables/
• Ant Design CLI: https://ant.design/docs/react/cli/
• Ant Design MCP Server: https://ant.design/docs/react/mcp/
• LLMs.txt guide: https://ant.design/docs/react/llms/
• LLM navigation file: https://ant.design/llms.txt
• Full LLM docs: https://ant.design/llms-full.txt
• Semantic LLM docs: https://ant.design/llms-semantic.md

Ecosystem References

• Ant Design X: https://x.ant.design/
• Ant Design Charts: https://charts.ant.design/
• AntV: https://antv.antgroup.com/
• Ant Design Pro: https://pro.ant.design/
• Pro Components: https://procomponents.ant.design/
• Ant Design Mobile: https://mobile.ant.design/
• Ant Design Mini: https://mini.ant.design/
• Ant Design Web3: https://web3.ant.design/
• Ant Design Landing: https://landing.ant.design/
• Scaffolds: https://scaffold.ant.design/
• Umi: https://umijs.org/
• dumi: https://d.umijs.org/
• qiankun: https://qiankun.umijs.org/
• Kitchen: https://kitchen.alipay.com/
• Ant Design Blazor: https://antblazor.com/

Follow-Up Questions Worth Deciding

1. Should the project explicitly market the controls story as "Ant-inspired", or should Ant remain internal inspiration and research lineage?
2. What should the final template values be named: wcag/ant, or more explicit names such as wcag-aa/ant-design?
3. Should Ant semantic tokens be public API, or should they remain an internal style system behind the existing Theme record?
4. Should token derivation be explicit DTCG values first, or should the generator learn Ant-like color/radius/spacing algorithms?
5. Which first vertical slice proves the adoption best: button states, form validation, data-grid/table, or the generated workbench/list-page template?

Recommended First Slice

The highest-signal first implementation slice is:

1. Add the design-system selector contract to the template/UI story: --design-system wcag|ant, with wcag as the compatibility default.
2. Add an Ant-inspired semantic-token and color-policy design doc.
3. Add internal semantic roles for primary, success, warning, error, info, surface, border, selected, hover, focus, and secondary text.
4. Implement the policy-backed color checker with wcag and ant providers.
5. Implement a style resolver for buttons, text inputs, list rows, tabs, and data-grid rows/cells.
6. Update the showcase specs so the Controls Gallery presents an Ant-inspired enterprise shell and pattern pages.
7. Add the local fs-skia-ant-design skill and sync it to .claude.

This slice is narrow enough to govern and test, but broad enough to make the UI story visibly different.