# Default design system -- Yujin DS first

Fetch when the user discusses UI / component design / look-and-
feel (signals: "componente", "modal", "sidebar", "card", "view",
"icon", "color", "fuente", "diseno", "interfaz", "UI", "form",
"button", "table", "kanban", "tabs"). Auto-injected on every
turn whose intent matches the UI heuristic.

## Rule (single source of truth)

The default front-end design system for any Forge-generated
project is **Yujin Design System** (`yujin-design-system/`). The
package ships with 258 DTCG-compliant tokens, 30 NAC3-attributed
component templates, 170 sumi-e icons + a kanji wordmark
catalog, and font references (Google Fonts CDN, no bundled
binaries).

When the user asks for a UI element, agents MUST:

1. Consult `yujin.design.list-templates` to see which Yujin
   components cover the kind of element being requested.
2. Use `yujin.design.get-template({slug})` to retrieve the HTML
   + CSS + `nac3_attrs` + variants for the picked component.
3. Splice the template into the project; do NOT hand-roll an
   equivalent layout from scratch.
4. Iconography: only pick from `yujin.design.list-sumie` (170
   canonical icons). Use `yujin.design.get-icon({slug})` to
   inline the SVG. Do NOT generate or import third-party icons
   (no Material, no Font Awesome) unless the user explicitly
   asks (override flow below).
5. Colors / typography / spacing: only via tokens from
   `yujin.design.tokens()`. Do NOT hardcode `#3A4DBC` or
   `font-family: Inter`; use `var(--color-accent)` and
   `var(--font-family-sans)`.

## Override flow

The user CAN override the default ("usa shadcn", "use Material",
"this app needs Tailwind only", "I want my own brand colors"):

- Agent invokes `yujin.design.override({system_id, reason})`.
- This is `policy: 'approval_required'` so R8 opens a modal.
- The user confirms (or rejects); the choice persists in
  `tenant_config.design_override`.
- Subsequent turns honor the override + the doctrine becomes a
  soft suggestion ("Yujin DS is the Forge default, but this
  tenant has overridden to <system>").

## Why this is the default

- Coherent visual language across every Forge-generated product
  -- the user does not need to re-learn the look-and-feel per
  product.
- 30 components are enough to compose every standard SaaS UX
  (CRM, admin panel, marketing site, e-commerce, dashboard,
  task tracker, settings).
- NAC3 attributes pre-applied -- every Yujin component is
  voice-controllable + accessibility-ready out of the box.
- 170 sumi-e icons cover virtually every business concept
  (finance, sales, support, manufacturing, quality, HR, mobile,
  AI, comms, document, geo, weather, animal). One coherent
  illustration style.

## Files in the package

```
yujin-design-system/
  manifest.json                 catalog + version + license
  tokens/
    yujin-tokens.json           258 DTCG W3C tokens
    yujin-tokens.css            generated CSS (same source-of-truth)
  components/
    _index.json                 list of 30 components by category
    button.yujin.json           one file per component
    card.yujin.json
    ...                         (30 total)
  icons/
    sumie/
      manifest.json             170 icons with tags
      branch-sakura.svg         one SVG file per icon
      ...                       (170 total)
  fonts/
    README.md                   reference-only policy (Google Fonts CDN)
```

## Six NAC3 verbs

| Verb                            | Returns                                            | Policy             |
|---------------------------------|----------------------------------------------------|--------------------|
| `yujin.design.list-templates`   | `[{slug, category, description, variants}]`       | safe               |
| `yujin.design.get-template`     | full ComponentTemplate (html, css, nac3, props)   | safe               |
| `yujin.design.list-sumie`       | `[{slug, tags, file}]` (filtered by tag if given) | safe               |
| `yujin.design.get-icon`         | inline SVG string                                  | safe               |
| `yujin.design.tokens`           | full DTCG token tree                               | safe               |
| `yujin.design.override`         | persists tenant_config.design_override            | approval-required  |

## What this doctrine does NOT cover

- Framework choice within TypeScript (Vue vs React vs Svelte).
  See `docs/doctrine/language-sovereignty.md` -- the user
  decides per slot, and the doctrine table records the choice.
- Build tooling (Vite vs Webpack vs esbuild). Out of scope.
- Theme switching per tenant. The override flow above persists
  one choice per tenant; multi-theme support is a separate
  feature.

## What the WORKERS (Analyst, Coder, Director) do with this

- **Analyst**: when extracting a spec that mentions UI elements
  (forms, dashboards, modals), tag each one with the matching
  Yujin component slug in `plan.components[]`. The Coder then
  knows which template to pull.
- **Coder**: before writing ANY UI file, invoke
  `yujin.design.list-templates` + `yujin.design.get-template`
  for the components in the plan. Splice the templates. Apply
  variants from the spec. Do NOT hand-write `.css` from
  scratch.
- **Director**: when the user explicitly requests an override
  ("use shadcn"), invokes `yujin.design.override` instead of
  silently accepting. The R8 modal confirms.

## Variants -- selectable design systems (PND-112)

The Yujin DS ships in two variants. The sumi-e one is the
DEFAULT; the art deco one is opt-in per product / panel.

- **`yujin-design-system`** (default) -- sumi-e aesthetic:
  indigo/teal/amber tones, 170 sumi-e icons, kanji wordmarks.
- **`yujin-design-system-artdeco`** -- pastel art deco: powder
  blues + warm slate grays + creams + a sparing brass rule,
  Poiret One / Josefin Sans typography, 48 geometric art deco
  icons. NO kanji, NO sumi-e. Crisper geometry (radii 2/4/8).

Both expose the SAME semantic token contract (`--color-accent`,
`--color-bg-*`, `--color-text-*`, `--color-border-*`, state
colors) and SHARE the same 30 components (theme-agnostic --
they consume `var(--color-*)`), so picking a variant is purely
a token + icon swap, never a component rewrite.

Selection: the resolver (`src/design/yujin_design_resolver.ts`)
takes a `ds` selector on every reader (`getManifest({ds})`,
`getTokensCss({ds})`, `listIcons(tag,{ds})`, `getIconSvg`,
`listTemplates`, `getTemplate`). `ds: 'artdeco'` -> the pastel
variant; absent / `'sumie'` / `'default'` -> the sumi-e default.
`getTokensCss({ds})` returns the theme CSS a generated product
or the panel injects to apply the look.

When a product should use the art deco look (signals: "art
deco", "pastel", "elegante geometrico", "sin kanjis", "estetica
clasica/dorada"), select the artdeco variant; otherwise keep the
sumi-e default. The icon catalog of the SELECTED variant is the
only one to pull from (no mixing sets).
