@urbicon-ui/design 6.1.8

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@urbicon-ui/design",
+  "version": "6.1.8",
+  "description": "The urbicon CLI — version-pinned design validation and design-manifest tooling for projects built with Urbicon UI. Wraps @urbicon-ui/design-engine for editor hooks and CI.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeberg.org/urbicon/ui.git",
+    "directory": "packages/design"
+  },
+  "homepage": "https://ui.urbicon.de",
+  "bugs": "https://codeberg.org/urbicon/ui/issues",
+  "keywords": [
+    "design-system",
+    "cli",
+    "linter",
+    "design-tokens",
+    "urbicon-ui",
+    "ai"
+  ],
+  "type": "module",
+  "bin": {
+    "urbicon": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "templates",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "bun build ./src/cli/index.ts --target node --outfile dist/cli.js",
+    "dev": "bun run --watch src/cli/index.ts",
+    "start": "bun run src/cli/index.ts",
+    "check": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "dependencies": {
+    "@urbicon-ui/design-content": "6.1.8",
+    "@urbicon-ui/design-engine": "6.1.8"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "@types/node": "^25.9.3",
+    "vitest": "^4.1.9"
+  },
+  "author": "Urbicon UI Team"
+}

package/skill/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: urbicon-design
+description: Design verbs for projects built on Urbicon UI — onboard, adopt, compose, redesign, polish, critique, fix, retheme, audit, migrate. Each is a recipe over the four design planes (knowledge · judgment · memory · action) that reads the project's design.manifest.md, does the work through the Urbicon tools, and writes the decision back.
+---
+
+# Urbicon design verbs
+
+A use-case verb is a **recipe**, not a single tool call: it strings the Urbicon
+knowledge (`get_pattern`, `get_css_reference`, `get_design_principles`), the
+deterministic judgment (`validate_design` / `urbicon validate`, the rubric), and
+the per-project memory (`design.manifest.md`) into one loop so generation does not
+regress to a generic template.
+
+**Same recipe text, two ways to run it.** Every verb ships both as an MCP prompt
+(invoke it from any MCP client) and as one of these local recipe files. The body is
+identical; pick whichever your harness exposes. Locally you can also print a recipe
+with `urbicon verb <name>` (and list them with `urbicon verbs`).
+
+## Two invariants, every verb
+
+1. **Read the manifest first.** Start by recovering the project's intent and
+   decisions — `urbicon context`, or read `./design.manifest.md` directly: paradigm,
+   theme, density, the Product Intent (audience, voice, references, anti-references),
+   the Token Overrides, the Pattern Usages, and the recorded ADRs. This is the
+   difference between "consistent with *this* product" and merely "generic".
+2. **Write the decision back.** End by persisting any state you changed — refresh
+   the Pattern Usages (`urbicon sync-manifest`), append an ADR for a deliberate
+   deviation (`urbicon record-decision`), or update the Product Intent / Token
+   Overrides. A choice the next session can't see will be silently undone.
+
+## Router — intent → verb
+
+| If the user wants to… | Verb | Gate |
+| --- | --- | --- |
+| Start a greenfield project, set its design identity | `onboard` | — |
+| Bring an existing codebase under the design system | `adopt` | — |
+| Build a new page or component from a brief | `compose` | correctness + slop + rubric |
+| Rework an existing page that feels wrong | `redesign` | correctness + slop + rubric |
+| Tighten a page that is already close | `polish` | slop-floor |
+| Judge a page without changing it | `critique` | (assessment only) |
+| Repair broken tokens / `dark:` / `focus:` / z-index | `fix` | correctness |
+| Rebrand the system (colour, type, density) | `retheme` | correctness over affected files |
+| Check consistency across the whole app | `audit` | (assessment over n pages) |
+| Roll out a pattern or library change everywhere | `migrate` | correctness per file |
+
+When the intent is ambiguous, prefer the **narrowest** verb that fits: `polish`
+before `redesign`, `fix` before `compose`. Escalate only if the narrow verb's
+diagnosis shows the problem is bigger than its remit.
+
+## The tools a recipe leans on
+
+- **Knowledge** — `find_components`, `get_component`, `get_pattern`, `get_recipe`,
+  `get_css_reference`, `find_icons`, `get_design_principles` (add `as="rubric"` for
+  the 8-criterion scorer; `topic="theming"` for a paradigm's token profile).
+- **Judgment** — `validate_design(code, extraTokens?)` (remote) or `urbicon validate`
+  (local hook/CI): two axes, correctness (the blocking gate) + slop-floor (advisory).
+- **Memory** — `urbicon context` / `record-decision` / `sync-manifest`, or your own
+  file tools on `./design.manifest.md` and its `*.history.ndjson` sidecar.
+
+Use only real semantic tokens — never invent `bg-status-*`, `text-*-foreground`,
+`bg-card`. When in doubt, `get_css_reference`.

package/skill/verbs/adopt.md

@@ -0,0 +1,33 @@
+# adopt — bring an existing codebase under the design system
+
+**When:** a project already has UI but no (or a thin) `design.manifest.md`. Infers
+the de-facto design language from the code and records it, surfacing the drift
+between what the code does and what Urbicon expects.
+**Gate:** none — this verb writes memory and reports; it doesn't rewrite UI.
+
+1. **Read what's already recorded.** `urbicon context`. Anything present (a chosen
+   paradigm, a prior ADR) constrains what you infer — don't contradict it silently.
+2. **Index the patterns.** `urbicon sync-manifest` to scan for
+   `data-design-pattern="…"` markers and (re)build the Pattern Usages section. If
+   the code has no markers yet, note which page archetypes you recognise and propose
+   adding markers (see `get_pattern` for the archetype names).
+3. **Infer the token reality.** Grep the source for the colour / spacing / radius
+   utilities actually in use. Sort them into: real Urbicon semantic tokens; project
+   tokens defined on top of Urbicon (→ candidates for `## Token Overrides`); and raw
+   palette / hallucinated tokens (→ drift to fix later with `fix`). Cross-check
+   names against `get_css_reference`.
+4. **Infer the intent.** From the components, copy, and density, draft a **Product
+   Intent** (audience, voice, references, anti-references) and confirm it with the
+   user — inference seeds it, the user ratifies it. Don't invent an audience the
+   code doesn't evidence.
+5. **Measure the drift.** Run `urbicon validate src/ --record` over the tree. The
+   correctness score is the gap to close; the slop-floor score is how generic it
+   reads today. `--record` writes the first history entry so future runs show the
+   trend.
+6. **Seed the manifest.** Write the inferred `## Product Intent`, the confirmed
+   `## Token Overrides`, and the synced `## Pattern Usages`. Append an ADR recording
+   that the manifest was *adopted from existing code* on this date (so later readers
+   know it's inferred, not designed-first).
+7. **Report.** Summarise: paradigm, intent, N project tokens, M patterns in use, and
+   the top correctness/slop offenders — with `fix` / `retheme` / `audit` as the
+   suggested follow-ups.

package/skill/verbs/audit.md

@@ -0,0 +1,29 @@
+# audit — check design consistency across the whole app
+
+**When:** a periodic or pre-release sweep — is the app still coherent, or has it
+drifted? The flagship cross-page verb: it reasons over *many* surfaces via the
+manifest usage-index, which no single-page or system-agnostic tool can do.
+**Gate:** none — assessment over n pages. Change nothing; produce a drift report.
+
+1. **Context + index.** `urbicon context` for the intent and recorded decisions, then
+   `urbicon sync-manifest` so the Pattern Usages index reflects the current tree.
+2. **Validate the tree.** `urbicon validate src/ --json --record` over the whole app.
+   `--record` appends a drift entry to the history sidecar; `urbicon context` then
+   shows the correctness/slop trend over time — the measure of whether the app is
+   getting more or less generic.
+3. **Check each pattern cohort.** For every pattern in the usage-index, read the files
+   listed under it and confirm they actually follow that pattern's rules
+   (`get_pattern("<name>")`). A page marked `dashboard` that looks like a form is
+   drift.
+4. **Score a representative sample.** Pick the highest-traffic or most-divergent pages
+   and score them with `get_design_principles(as="rubric")`. Look for *spread* — wide
+   variance across pages is the consistency problem, even if each page passes alone.
+5. **Report drift, don't fix it.** Produce: the app-wide correctness/slop scores and
+   their trend; per-pattern conformance; the rubric spread; and a ranked list of the
+   worst offenders, each tagged with the verb that repairs it (`fix`, `polish`,
+   `redesign`, `retheme`).
+6. **Persist the finding.** Offer to append an ADR summarising the audit (date,
+   scores, top drift) so the next audit has a baseline to compare against — the
+   history sidecar plus an ADR make drift measurable, not anecdotal.
+
+Output: the drift report. Recommend, but do not perform, the repairs.

package/skill/verbs/compose.md

@@ -0,0 +1,38 @@
+# compose — design a new page or component from a brief
+
+**When:** building something new. Runs the full generate → validate → judge →
+synthesise loop so a single-shot answer can't regress to a generic template.
+**Gate:** correctness (blocking) + slop-floor (advisory) + the rubric.
+
+Do not skip steps. The value is in the loop, not any one generation.
+
+1. **Context.** `urbicon context` (or read `./design.manifest.md`) — honour the
+   paradigm, theme, density, the Product Intent (design *toward* its voice and
+   references, *away* from its anti-references), and the recorded ADRs. Then, if a
+   composition pattern fits the brief, `get_pattern("<name>")` (settings-page,
+   dashboard, form-page, tab-navigation, onboarding-guide, planning-board) and
+   follow its layout, component-selection, and behavioural rules.
+2. **Ground rules.** `get_design_principles` for the heuristics,
+   `get_design_principles(topic="theming")` for the paradigm's token profile, and
+   `get_css_reference` for the exact token names. `find_components` /
+   `suggest_implementation` to pick the right primitives rather than reinventing them.
+3. **Generate variants.** Produce a few genuinely different implementations (2–5;
+   default 3), each a distinct compositional approach *within* the paradigm — vary
+   density, hierarchy emphasis, and the one signature moment. Do not let them
+   converge. Use only real semantic tokens (no `bg-status-*`, no `*-foreground`, no
+   invented names); if the project defines its own, they're in `## Token Overrides`.
+4. **Validate.** Run `validate_design` (or `urbicon validate`) on every variant. Fix
+   each error and warning. A variant that can't reach a clean correctness score is
+   disqualified. Note each one's slop-floor score — lower is more generic.
+5. **Judge.** `get_design_principles(as="rubric")` and score each survivor /40.
+   Prefer a panel: judge correctness, hierarchy, paradigm-fidelity, and
+   distinctiveness as separate lenses, not one gut number.
+6. **Synthesise.** Pick the winner, then graft the best ideas from the runners-up.
+   Run `validate_design` once more on the merged result — it must come back clean.
+7. **Record.** If the page follows a pattern, add `data-design-pattern="<name>"` to
+   its root and refresh Pattern Usages (`urbicon sync-manifest`). Append an ADR
+   (`urbicon record-decision`) for any deliberate deviation from a pattern or
+   principle.
+
+Output the final code, then a one-line, honest rationale per major choice — name the
+trade-offs.

package/skill/verbs/critique.md

@@ -0,0 +1,27 @@
+# critique — judge a page without changing it
+
+**When:** the user wants an assessment, a review, or a prioritised punch-list — not
+edits. Produces a diagnosis you (or `redesign` / `polish` / `fix`) can act on later.
+**Gate:** none — this verb only assesses. Change nothing.
+
+1. **Context.** `urbicon context` for the paradigm and Product Intent — a critique
+   is *against this project's* identity, not a generic best-practices checklist.
+2. **Run the full stack.** On the page's code:
+   - **Correctness** — `validate_design` (or `urbicon validate`): errors and warnings
+     are deterministic defects (raw colours, `dark:`/`focus:` misuse, hardcoded
+     z-index, broken dynamic classes, hallucinated tokens).
+   - **Slop-floor** — the same run's advisory notes: where it reads generic.
+   - **Taste** — `get_design_principles(as="rubric")` and score /40 across the eight
+     criteria.
+3. **Prioritise.** Order the findings by impact, not by severity label: a single
+   broken hierarchy outranks five cosmetic nits. Tie each to the rubric criterion or
+   linter rule it comes from, so the fix is unambiguous.
+4. **Recommend the verb.** For each cluster, name the right follow-up — `fix` for
+   correctness, `polish` for slop, `redesign` for a low rubric score — so the user
+   can act in one step.
+5. **Offer to record.** If the critique surfaces a *systemic* gap (not a one-page
+   issue), offer to append an ADR or open it as drift in the manifest. Don't write
+   without asking — critique's contract is read-only.
+
+Output: the two scores (correctness · slop-floor), the rubric /40 with the two
+weakest criteria called out, and the prioritised fix-list with a verb per item.

package/skill/verbs/fix.md

@@ -0,0 +1,29 @@
+# fix — repair correctness defects
+
+**When:** the linter's blocking gate is red — raw Tailwind colours, `dark:` overrides,
+`focus:` instead of `focus-visible:`, hardcoded z-index, broken dynamic classes, or
+hallucinated tokens. Mechanical, behaviour-preserving corrections.
+**Gate:** correctness — every error and warning must clear.
+
+1. **Context.** `urbicon context` — so a token you're tempted to "fix" that is
+   actually a declared project token (in `## Token Overrides`) is left alone. Pass
+   those as `extraTokens` to `validate_design`; `urbicon validate` reads them from the
+   manifest automatically.
+2. **Enumerate.** Run `validate_design` (or `urbicon validate`) and list every
+   **error** and **warning** with its rule id and location. Ignore the slop-floor
+   notes here — that's `polish`.
+3. **Map each to its correct token.** `get_css_reference` for the real names:
+   - raw palette (`bg-red-500`) → the semantic intent (`bg-danger`, `text-on-primary`).
+   - `dark:` override → delete it; semantic tokens handle dark mode via `light-dark()`.
+   - `focus:` → `focus-visible:`.
+   - hardcoded z-index → a `z-[var(--z-*)]` token.
+   - hallucinated token (`bg-status-danger`, `text-*-foreground`) → the real one, or a
+     `## Token Override` if the project genuinely defines it.
+4. **Apply and re-validate.** Make the substitutions, change nothing else, and run the
+   linter again. Repeat until correctness is clean. Behaviour and layout must be
+   identical — this verb does not redesign.
+5. **Record only a systemic fix.** A scattered cleanup needs no ADR. If you
+   discovered the project legitimately needs a token, add it to `## Token Overrides`
+   (so it stops being flagged) and note why.
+
+Output the diff and confirm a clean correctness score.

package/skill/verbs/migrate.md

@@ -0,0 +1,30 @@
+# migrate — roll out a pattern or library change everywhere
+
+**When:** a composition pattern, component API, or library convention changed and
+every site of it must move in lockstep — e.g. "the settings-page pattern now uses
+tabs" or "Card lost its `elevated` prop".
+**Gate:** correctness per file — each migrated file must pass before the next.
+
+1. **Context.** `urbicon context` — the manifest's decisions tell you which
+   conventions are deliberate (don't migrate away from a recorded ADR without
+   superseding it).
+2. **Pin the before/after.** State the exact change: old construct → new construct.
+   If it's a pattern change, re-read both via `get_pattern`; if a component API change,
+   `get_component` for the new contract.
+3. **Find every site.** `urbicon sync-manifest`, then use the Pattern Usages index
+   (for pattern changes) and a grep of the old construct (for API/markup changes) to
+   enumerate the files. Report the count up front — a silently partial migration is
+   worse than none.
+4. **Transform file by file.** Apply the change to one file, run `validate_design` /
+   `urbicon validate`, and only then move on. Keep each file's diff minimal and
+   behaviour-preserving. If a file resists the mechanical transform, flag it for
+   manual `redesign` rather than forcing it.
+5. **Re-index and validate the whole.** `urbicon sync-manifest` again so the index
+   reflects the new reality, then `urbicon validate src/ --record` for a clean
+   end-state baseline.
+6. **Record the migration.** Append an ADR: what changed, why, how many files moved,
+   and any deliberately skipped (with the reason). The next person needs to know the
+   migration is complete and where the exceptions are.
+
+Output: the file count, the per-file pass status, and any sites deferred to manual
+follow-up.

package/skill/verbs/onboard.md

@@ -0,0 +1,33 @@
+# onboard — set a greenfield project's design identity
+
+**When:** a new project with no `design.manifest.md` yet. Establishes the target
+identity and the enforced intake decisions, so every later verb has an anchor.
+**Gate:** none — this verb writes memory, it doesn't generate UI.
+
+Run a short interview, then seed the manifest. Do not skip the interview: a manifest
+with only defaults gives later verbs nothing to be consistent *with*.
+
+1. **Check for an existing manifest.** `urbicon context` (or look for
+   `./design.manifest.md`). If one already exists with real intent, stop and suggest
+   `adopt` or `audit` instead — onboarding twice overwrites a considered identity.
+2. **Interview the product intent.** Ask the user — one question at a time, accept
+   terse answers — for:
+   - **Audience:** who uses this, their context, constraints, expertise.
+   - **Voice:** three adjectives (e.g. *calm, precise, trustworthy*).
+   - **References:** one or two products whose feel to move toward.
+   - **Anti-references:** the generic defaults to avoid (e.g. "Bootstrap admin").
+3. **Settle the intake decisions.** Pick a **paradigm** (call
+   `get_design_principles(topic="theming")` to see the profiles), a **theme**, and a
+   **density**. Explain the trade-off in one line each; default to Minimal /
+   default / comfortable if the user is unsure.
+4. **Seed the manifest.** Write `./design.manifest.md`: the frontmatter
+   (`paradigm` / `theme` / `density`), and the `## Product Intent` section with the
+   interview answers. `urbicon` writes a scaffold on first command, or author the
+   file directly — keep the section headings exactly (`## Product Intent`,
+   `## Token Overrides`, `## Pattern Usages`, `## Design Decisions`).
+5. **Record the founding decision.** Append one ADR capturing *why* this paradigm
+   and voice (`urbicon record-decision --title "…" --decision "…" --rationale "…"`).
+   It is the reference the team — and the next session — argues against.
+6. **Hand off.** Tell the user the identity is set and point them at `compose` for
+   the first page. Confirm the manifest parses: `urbicon context` should echo the
+   intent back.

package/skill/verbs/polish.md

@@ -0,0 +1,25 @@
+# polish — tighten a page that is already close
+
+**When:** the structure is right but it reads a little generic — uniform spacing, a
+default font, low-contrast text, a magic-number size. Small targeted fixes, no
+rebuild.
+**Gate:** slop-floor (the advisory "looks generic" axis) — and never regress
+correctness.
+
+1. **Context.** `urbicon context` for the Product Intent — polish moves the page
+   *toward* its voice, not toward your taste.
+2. **Find the slop.** Run `validate_design` (or `urbicon validate`) and read the
+   **slop-floor** findings specifically (the advisory notes): generic font, uniform
+   spacing/weights, identical cards, grey-on-colour, animated dimensions,
+   magic-number sizes, small touch targets, emoji-as-icon, and so on.
+3. **Fix the smallest things that raise the slop-floor score.** One change at a time;
+   keep each reversible. Reach for the design system's real tokens and scale steps —
+   `get_css_reference` for names — rather than ad-hoc values. Do **not** restructure;
+   if a finding needs structural change, that's `redesign`, not `polish`.
+4. **Re-validate.** Run the linter again. The correctness score must not drop; the
+   slop-floor score should rise. Stop when the remaining findings are deliberate.
+5. **Record only if it's a rule.** A one-off tweak needs no ADR. If you set a
+   repeatable convention (e.g. "stat tiles use `surface-elevated`, not a border"),
+   append an ADR so the next page inherits it.
+
+Output the diff (or the changed snippets) and the slop-floor score before → after.

package/skill/verbs/redesign.md

@@ -0,0 +1,29 @@
+# redesign — rework an existing page that feels wrong
+
+**When:** a page exists but underperforms — flat, generic, off-identity. Diagnoses
+first, then fixes exactly what the diagnosis flags, preserving behaviour.
+**Gate:** correctness (blocking) + slop-floor (advisory) + the rubric.
+
+A diagnosis-first loop — resist the urge to rebuild from scratch.
+
+1. **Context.** `urbicon context` (or read `./design.manifest.md`) to recover the
+   paradigm, theme, Product Intent, and prior decisions. Read the current
+   implementation of the page in question.
+2. **Diagnose.** Run `validate_design` (or `urbicon validate`) on the current code,
+   then `get_design_principles(as="rubric")` and score the page /40. Your revision
+   targets are **every linter finding** (correctness *and* slop-floor) plus the
+   **two lowest-scoring rubric criteria** — nothing else. Write the targets down.
+3. **Generate variants.** Produce a few options (2–5; default 3) that fix exactly
+   those weaknesses. Preserve the page's behaviour, data flow, and overall structure;
+   change only what the diagnosis flagged. Use only real tokens (project tokens are
+   in `## Token Overrides`).
+4. **Validate.** Run the linter on each; fix every error and warning.
+5. **Judge.** Re-score each variant with the rubric. A redesign that does not beat
+   the original on its target criteria is not shippable — say so and iterate.
+6. **Synthesise.** Merge the best result, then run `validate_design` once more — it
+   must come back clean.
+7. **Record.** Append an ADR for any deliberate deviation (`urbicon record-decision`);
+   refresh Pattern Usages (`urbicon sync-manifest`) if pattern usage changed.
+
+End with a before/after table of the targeted criteria (old score → new score), then
+the final code and a one-line, honest rationale per major change.

package/skill/verbs/retheme.md

@@ -0,0 +1,29 @@
+# retheme — rebrand the system across every surface
+
+**When:** the design language itself changes — new brand colour, type, density, or
+paradigm — and it must propagate everywhere consistently. The flagship verb: only
+possible because there's a real token system plus a manifest usage-index to drive it.
+**Gate:** correctness over every affected file.
+
+1. **Context + scope.** `urbicon context` for the current paradigm, theme, and
+   `## Token Overrides`. State precisely what's changing and what's staying — a
+   retheme that touches everything is a rewrite, not a rebrand.
+2. **Decide at the right layer.** `get_design_principles` includes a change-decision
+   tree: a colour shift is usually a **semantic-token** remap, not a per-component
+   edit. Change the foundation/semantic layer (or the project's `## Token Overrides`),
+   not 200 call-sites — that's the whole point of the token architecture.
+3. **Update the source of truth.** Apply the token changes once at the layer you
+   chose, and update `## Token Overrides` in the manifest so `validate` accepts the
+   new vocabulary and rejects the old.
+4. **Find every affected surface.** Use the manifest's Pattern Usages and a grep of
+   the changed token names to list the files that actually render them. The
+   usage-index is what makes "everywhere" tractable instead of a guess.
+5. **Propagate and validate per file.** For each affected file, apply the remap and
+   run `validate_design` / `urbicon validate`. The gate is per file: none may ship
+   with a stale or raw token. `urbicon validate src/ --record` at the end captures the
+   post-retheme drift baseline.
+6. **Record the rebrand.** Append one ADR describing the change, the layer it was made
+   at, and the old→new token mapping — the migration note future readers need.
+
+Output: the layer-level change, the list of propagated files, and a clean
+correctness score across all of them.

package/templates/AGENTS.md

@@ -0,0 +1,84 @@
+<!-- urbicon:start — Urbicon UI agent context. Managed by `urbicon init`: it inserts and
+updates everything between these two markers, so edit *outside* them (or run `init` again
+to refresh). Pasting this by hand? Keep the markers if you want `init` to manage it later;
+delete them if you don't. -->
+
+## Urbicon UI
+
+This project builds its UI with [Urbicon UI](https://ui.urbicon.de) — Svelte 5 + Tailwind 4
+components on a token-based design system. **Compose from the system; don't hand-roll UI or
+invent styles.** The `urbicon` CLI (a devDependency, run as `bunx urbicon <command>`) puts the
+design system's knowledge, linter and memory at your fingertips — **version-matched to the
+library this project installed**, so what it tells you is true of the code you actually have.
+
+### Tools — the `urbicon` CLI
+
+- **Discover & read components** (before you compose):
+  - `urbicon find <query>` — fuzzy-search the catalog, e.g. `urbicon find "date range"`.
+  - `urbicon get-component <slug>` — a component's real API: props, variants, examples
+    (`--section api|examples|variants|slots|full`).
+- **Validate** what you generate:
+  - `urbicon validate <path>` — lint markup against the design rules; fix every error.
+- **Read & record design intent** (the project's memory):
+  - `urbicon context` — the design manifest: paradigm, voice, decisions. Read it first.
+  - `urbicon record-decision …` — log a deliberate design choice so the next session sees it.
+  - `urbicon sync-manifest` — re-index pattern usages from the code.
+- **Whole-task recipes** — `urbicon verbs` / `urbicon verb <name>` (also a `/`-skill,
+  `urbicon-design`, if installed).
+
+Beyond what the CLI prints, the hosted knowledge lives at <https://ui.urbicon.de> (and the
+`urbicon-ui` MCP server, if your client has it connected). Both serve **latest** — when it
+disagrees with the local CLI, **trust the CLI**: it matches this project's installed version.
+
+### How to work — the design loop
+
+1. **Read the intent** — `urbicon context`. This is what keeps output consistent with *this*
+   product instead of generic.
+2. **Discover** — `urbicon find` / `get-component` for the right component and its real API.
+3. **Compose** from real components + semantic tokens (rules below).
+4. **Validate** — `urbicon validate`; fix every correctness error before shipping. (Slop notes
+   are advisory — raise them when it's cheap.)
+5. **Write the decision back** — `urbicon record-decision` for a deliberate deviation. What the
+   next session can't see, it will silently undo.
+
+For a whole task, pick a **verb** (a recipe over that loop): `compose` (new page) ·
+`redesign` (rework) · `polish` (tighten) · `fix` (repair tokens) · `critique` / `audit` (judge
+without changing) · `retheme` / `migrate` (roll a change out). Prefer the narrowest that fits.
+
+### Hard rules — the linter enforces these
+
+**Import from the package root only** — never a deep/internal path:
+
+```ts
+import { Button, Card, Dialog } from '@urbicon-ui/blocks'; // ✓
+// import Button from '@urbicon-ui/blocks/primitives/Button/Button.svelte'; // ✗
+```
+
+**USE semantic tokens** (the canonical set; `urbicon get-component` shows them in context):
+
+- Surface — `bg-surface-base` / `-elevated` / `-overlay`
+- Text — `text-text-primary` / `-secondary` / `-tertiary`
+- Border — `border-border-subtle` / `-default`
+- Intent — `bg-primary`, `text-primary`, `bg-primary-subtle` (`primary` `secondary` `success` `warning` `danger` `neutral`)
+- Elevation / motion / layer — `shadow-[var(--blocks-shadow-sm)]`, `duration-[var(--blocks-duration-fast)]`, `z-[var(--z-modal)]`
+
+**NEVER:**
+
+- `dark:` — semantic tokens already switch via CSS `light-dark()`.
+- Hardcoded colours (`bg-white`, `text-neutral-900`, `bg-blue-500`) or invented tokens (`bg-card`, `text-*-foreground`).
+- `focus:` — always `focus-visible:` (keyboard-only rings).
+- Hardcoded `z-index`, `cubic-bezier`, or duration values.
+
+**Off-palette looks** (brand colour, glass, translucent overlay) → register a **preset** at the
+app root and reference it by name; never force colours with inline `!` overrides:
+
+```svelte
+<BlocksProvider presets={{ Button: { brand: { slotClasses: { base: 'bg-[var(--brand)] text-white' } } } }}>
+  <Button preset="brand">Go</Button>
+</BlocksProvider>
+```
+
+**Svelte 5** — `$props()` not `export let`; `{#snippet}` / `{@render}` not `<slot>`; callback props
+(`onValueChange`) not `createEventDispatcher`; lowercase DOM events (`onclick`).
+
+<!-- urbicon:end -->

package/templates/ci-github.yml

@@ -0,0 +1,26 @@
+# Urbicon UI design gate — fail the build when generated/edited markup drifts
+# from the design rules. Copy into .github/workflows/, or merge the `design` job
+# into an existing workflow. Requires @urbicon-ui/design in devDependencies.
+#
+# Using npm/pnpm + Node instead of Bun? Swap the setup-bun step for setup-node +
+# your install, and `bunx` for `npx` — the `urbicon` bin is plain Node-runnable.
+name: Design Gate
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  design:
+    name: Design gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      # Correctness is the blocking gate — deterministic, false-positive free.
+      # Add --slop-floor 40 to also gate the slop axis (a generic-looking page
+      # fails below the floor); add --record to append a drift point to the
+      # design.manifest.history.ndjson sidecar.
+      - run: bunx urbicon validate src/ --json

package/templates/claude-settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "urbicon hook"
+          }
+        ]
+      }
+    ]
+  }
+}