@urbicon-ui/design-content 6.1.8

package/content/meta.json

@@ -0,0 +1,5 @@
+{
+  "version": "6.1.8",
+  "builtAt": "2026-06-22T12:20:10.242Z",
+  "contentHash": "20b83a8bdb37"
+}

package/content/table/table/llm.txt

@@ -0,0 +1,110 @@
+
+---
+
+## Table
+Advanced data table component with smart filtering, column factories, responsive design,
+and extensible features for complex data visualization. Supports row selection, keyboard navigation,
+virtual scrolling, column reorder, server-side data, live updates, and custom cell components.
+
+**Import:** `import { Table } from '@urbicon-ui/table';`
+
+### Examples
+```svelte
+<Table
+items={data}
+columns={columns}
+itemsPerPage={25}
+enableSmartFilter={true}
+/>
+```
+
+```svelte
+{#snippet statusCell(item, value)}
+<Badge intent={value === 'active' ? 'success' : 'danger'}>{value}</Badge>
+{/snippet}
+
+<Table items={data} columns={[
+{ accessor: 'name', title: 'Name', sortable: true },
+{ accessor: 'status', title: 'Status', cell: statusCell }
+]} />
+```
+
+```svelte
+<Table
+items={data}
+columns={columns}
+selectionMode="multi"
+onSelectionChange={(selected) => console.log(selected)}
+/>
+```
+
+```svelte
+<Table
+mode="server"
+columns={columns}
+queryFn={async (query, { signal }) => {
+const res = await fetch(`/api/users?page=${query.page}`, { signal });
+return await res.json();
+}}
+/>
+```
+
+```svelte
+<Table items={tenThousandRows} columns={columns} virtualized virtualHeight="500px" />
+```
+
+```svelte
+<Table {items} {columns} persistenceConfig={{ tableId: 'expenses' }} />
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| appearance | `'flush' | 'surface' | 'framed'` | no | "flush" | Visual appearance of the table chrome (see docs/MIGRATION-v5.md §3): - `flush` (default): no outer frame, sits inline in the reading flow - `surface`: gentle `surface-quiet` tinted zone, no border - `framed`: bordered + rounded + shadowed standalone block |
+| ariaLabel | `string` | no | undefined | Accessible label for the table, announced by screen readers. |
+| autoApplyOnNavigation | `boolean` | no | true | Automatically apply pending live updates when the user navigates (page change, sort, filter, search). Since the view is already changing, applying buffered changes at this point is non-disruptive. |
+| body | `Snippet` | no | undefined | Body property for the Table component |
+| cell | `Snippet<[item: T, value: unknown, column: Column<T>]>` | no | undefined | Global cell snippet that overrides rendering for ALL columns. For per-column customization, prefer `column.cell` instead. |
+| class | `string` | no | undefined | Additional CSS class names for the table container |
+| columns | `Column<T>[]` | no | [] | Column configuration array defining the table structure |
+| empty | `Snippet` | no | undefined | Custom empty state snippet |
+| enableColumnReorder | `boolean` | no | false | Enable drag-and-drop column reordering on desktop. Users can drag column headers to rearrange them. Also supports keyboard reorder via Shift+ArrowLeft/Right on focused headers. |
+| enableLiveUpdates | `boolean` | no | false | Enable live update support. When enabled, a `LiveUpdateBanner` is shown when pending inserts/updates/deletes are buffered. Use `getTableContext()` to access `pushInsert`, `pushUpdate`, `pushDelete` from WebSocket/SSE handlers. |
+| enableSmartFilter | `boolean` | no | true | Enable smart filtering functionality |
+| error | `Snippet` | no | undefined | Custom error state snippet |
+| errorText | `string` | no | "Error loading data" | Text displayed on error |
+| expandedRowContent | `Snippet<[item: T]>` | no | undefined | Snippet to render expanded row content |
+| fit | `'content' | 'viewport'` | no | "content" | Make the table its own scroll container so wide **and** long lists scroll *within* the table instead of pushing overflow onto the page.  - `'content'` (default): the table grows with its content; vertical overflow   scrolls the page. Pair with `sticky` for page-relative pinning. - `'viewport'`: the table is height-capped to the viewport and becomes a   self-contained scroll box. The column header (and group header when   grouping) pin to the top of the box, while the toolbar and pagination stay   fixed outside the scrolling area — only the rows scroll, in both axes. The   available height is measured automatically (the container's distance from   the top of the viewport), so no magic `max-height` is needed in the   consumer, and it adapts to whatever sits above the table (tabs, banners).  Notes for `'viewport'`: - Desktop only (`md`+); mobile keeps normal document-level scroll. - Supersedes `sticky`: header/group pinning is intrinsic to the box, so the   `sticky` prop is ignored. `stickyOffset` is ignored too — the measured top   absorbs app-shell offsets automatically. - Mutually exclusive with `virtualized`, which manages its own bounded   scroll via `virtualHeight`; `fit` has no effect when `virtualized`. |
+| groupHeaderContent | `Snippet<[groupName: string, items: T[], isExpanded: boolean]>` | no | null | Custom content for group headers |
+| groupOrder | `string[]` | no | [] | Custom order for group display |
+| header | `Snippet` | no | undefined | Custom header snippet |
+| initialGroupBy | `string | null` | no | null | Initial grouping key (if no persisted value exists). When grouping is active, pagination is disabled — all grouped items are shown at once. |
+| initialPage | `number` | no | 1 | InitialPage property for the Table component |
+| initialSummaryConfigs | `SummaryConfig[]` | no | [] | Initial summary configurations (if no persisted value exists). Each entry defines a column + aggregation type (sum, avg, count, min, max). |
+| items | `T[]` | no | [] | Array of data items to display in the table. Items with an `id` property get better key stability for animations. If no `id` is present, the array index is used as fallback key. |
+| itemsPerPage | `number` | no | 10 | Number of items to display per page |
+| loading | `Snippet` | no | undefined | Custom loading state snippet |
+| loadingText | `string` | no | "Loading data..." | Text displayed during loading state |
+| mode | `'client' | 'server'` | no | "client" | Data processing mode. - `'client'` (default): Filtering, sorting, and pagination are done locally. - `'server'`: The table delegates all data operations to the server. Items passed via   `items` prop (or returned by `queryFn`) are displayed as-is. |
+| multiExpand | `boolean` | no | false | Allow multiple rows to be expanded simultaneously. When false (default), expanding a row collapses the previously expanded one. |
+| noDataText | `string` | no | "No data found." | Text displayed when no data is available |
+| onQueryChange | `(query: TableQuery) => void` | no | undefined | Callback fired when the table query changes in `mode: 'server'`. Use this for manual control — fetch data yourself and update `items`, `serverTotalItems`, `loading`, and `error` props accordingly. Fires after debounce (controlled by `queryDebounceMs`). |
+| onRowClick | `(item: T) => void` | no | undefined | Callback fired when a row is clicked. Receives the clicked row's data item. |
+| onSelectionChange | `(selectedItems: T[]) => void` | no | undefined | Callback fired when the selection changes. Receives the array of currently selected items. |
+| pagination | `Snippet` | no | undefined | Custom pagination snippet |
+| persistenceConfig | `TablePersistenceConfig` | no | undefined | Persist table view state across reloads. Pass `{ tableId: 'foo' }` to opt in — every axis (filters, search, group, summary, sort, column visibility, column order) is persisted by default into `localStorage` under keys scoped to `tableId`. Set individual `persist*` flags to `false` to keep an axis volatile.  Pagination (current page) is intentionally never persisted — page 1 on navigation is standard UX. |
+| queryDebounceMs | `number` | no | 300 | Debounce delay in milliseconds for server query changes. Prevents excessive requests during rapid filter/search input. |
+| queryFn | `(query: TableQuery, options: { signal: AbortSignal }) => Promise<TableQueryResult>` | no |  | Async function for managed server-side fetching. When provided in `mode: 'server'`, the table calls this function automatically when the query changes (debounced). The table manages loading/error states and request cancellation via `AbortSignal`. |
+| searchDebounceMs | `number` | no | 300 | Debounce delay for search in milliseconds |
+| searchPlaceholder | `string` | no | "Search..." | Placeholder text for search input |
+| selectedIds | `Array<string | number>` | no | undefined | Controlled selected row IDs. When provided, the component reflects this value instead of managing selection internally. |
+| selectionMode | `'none' | 'single' | 'multi'` | no | "none" | Row selection mode. - `'none'`: No selection (default) - `'single'`: Only one row can be selected at a time - `'multi'`: Multiple rows can be selected with checkboxes |
+| serverTotalItems | `number` | no | 0 | Total number of items on the server. Required when `mode` is `'server'` and manual control is used (without `queryFn`). Drives pagination calculation. |
+| size | `'sm' | 'md' | 'lg'` | no | "md" | Size variant for the table |
+| slotClasses | `Partial<TableSlotClasses>` | no | {} | Per-slot class overrides merged with (or replacing, if `unstyled`) variant styles. Available slots: `container`, `toolbar`, `scrollArea`, `table`, `thead`, `tbody`, `headerRow`, `headerCell`, `row`, `cell`, `groupHeader`, `summaryRow`, `emptyState`, `loadingState`, `errorState`, `filterBar`, `mobileCard`.  **Breaking change in v1.5:** the former `wrapper` slot has been replaced by `scrollArea`. The former hardcoded `overflow-hidden` on `wrapper` blocked `position: sticky`, see [docs/STICKY-PINNING.md](../../../../../docs/STICKY-PINNING.md). |
+| sticky | `boolean | 'toolbar' | 'header' | 'both'` | no | false | Pin toolbar/header/group-header to the top of the scroll ancestor on scroll. - `false` (default): no pinning, layout matches v1.4.x - `true` / `'both'`: toolbar + thead + group-header all pin - `'toolbar'`: only the toolbar pins - `'header'`: only the thead (and group-header when grouping is active) pins  Pair with `stickyOffset` for app shells that have a fixed top bar.  For tables wider than the viewport, prefer `fit="viewport"` — it contains horizontal scroll inside the table instead of falling back to page-level horizontal scroll (a sticky pin host cannot also be a horizontal scroll ancestor). `fit="viewport"` supersedes `sticky` when set. |
+| stickyOffset | `number` | no | 0 | Pixel offset for the topmost sticky layer (toolbar, or thead when no toolbar). Writes the CSS custom property `--blocks-table-sticky-top` on the container. Use this to push the pin below a fixed app shell top bar. |
+| toolbar | `Snippet` | no | undefined (renders default SmartFilterBar when enableSmartFilter) | Custom toolbar snippet. Replaces the default `SmartFilterBar`. Renders inside the sticky toolbar wrapper when `sticky` is enabled — so a custom toolbar inherits the pinning behavior without extra wiring.  Access the table context via `getTableContext()` to wire up custom filter UIs. |
+| unstyled | `boolean` | no | false | Remove default tailwind-variants classes. Only user-provided `slotClasses` apply. |
+| virtualHeight | `string` | no | "600px" | Height of the virtual scroll container. Only used when `virtualized` is true. Accepts any CSS height value. |
+| virtualized | `boolean` | no | false | Enable virtualization for large datasets. When enabled, only visible rows are rendered for performance with >1000 items. Pagination is bypassed — all filtered/sorted items are virtualized in a scrollable container. Not compatible with grouping (grouping takes precedence). |

package/content/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/content/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/content/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/content/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/content/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/content/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/content/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/content/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/content/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/content/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/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@urbicon-ui/design-content",
+  "version": "6.1.8",
+  "description": "Version-pinned bundle of Urbicon UI design knowledge — component catalog, per-component llm.txt, design-system principles + patterns, guide template and icon metadata — plus a package-relative locator. Consumed by the remote MCP server and the urbicon CLI.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeberg.org/urbicon/ui.git",
+    "directory": "packages/design-content"
+  },
+  "homepage": "https://ui.urbicon.de",
+  "bugs": "https://codeberg.org/urbicon/ui/issues",
+  "keywords": [
+    "design-system",
+    "component-catalog",
+    "urbicon-ui",
+    "ai",
+    "llm"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "content",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "echo 'no build needed — Bun runs TypeScript directly'",
+    "check": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "@types/node": "^25.9.3",
+    "vitest": "^4.1.9"
+  },
+  "author": "Urbicon UI Team"
+}

package/src/content-loader.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  getCatalogPath,
+  getComponentLlmPath,
+  getContentDir,
+  getDesignSystemDir,
+  getIconsPath,
+  getTemplatePath
+} from './content-loader.js';
+
+describe('content-loader paths', () => {
+  const original = process.env.URBICON_CONTENT_DIR;
+
+  afterEach(() => {
+    if (original === undefined) delete process.env.URBICON_CONTENT_DIR;
+    else process.env.URBICON_CONTENT_DIR = original;
+  });
+
+  describe('getContentDir', () => {
+    beforeEach(() => {
+      delete process.env.URBICON_CONTENT_DIR;
+    });
+
+    it('defaults to the package-relative content/ dir', () => {
+      expect(getContentDir().endsWith('/content')).toBe(true);
+    });
+
+    it('honours the URBICON_CONTENT_DIR override', () => {
+      process.env.URBICON_CONTENT_DIR = '/custom/bundle';
+      expect(getContentDir()).toBe('/custom/bundle');
+    });
+  });
+
+  describe('derived artifact paths', () => {
+    beforeEach(() => {
+      process.env.URBICON_CONTENT_DIR = '/bundle';
+    });
+
+    it('resolves each artifact under the content dir', () => {
+      expect(getCatalogPath()).toBe('/bundle/component-catalog.json');
+      expect(getDesignSystemDir()).toBe('/bundle/design-system');
+      expect(getTemplatePath()).toBe('/bundle/guides/llms-full-template.md');
+      expect(getIconsPath()).toBe('/bundle/icons.json');
+    });
+  });
+
+  describe('getComponentLlmPath', () => {
+    beforeEach(() => {
+      process.env.URBICON_CONTENT_DIR = '/bundle';
+    });
+
+    it('resolves a valid slug under its group', () => {
+      expect(getComponentLlmPath('blocks/primitives', 'button')).toBe(
+        '/bundle/blocks/primitives/button/llm.txt'
+      );
+    });
+
+    it('accepts multi-word hyphenated slugs', () => {
+      expect(getComponentLlmPath('blocks/components', 'date-picker')).toBe(
+        '/bundle/blocks/components/date-picker/llm.txt'
+      );
+    });
+
+    it('rejects uppercase, whitespace, and edge hyphens', () => {
+      expect(() => getComponentLlmPath('x', 'Button')).toThrow(/Invalid component slug/);
+      expect(() => getComponentLlmPath('x', 'bad slug')).toThrow(/Invalid component slug/);
+      expect(() => getComponentLlmPath('x', '-bad')).toThrow(/Invalid component slug/);
+      expect(() => getComponentLlmPath('x', 'bad-')).toThrow(/Invalid component slug/);
+    });
+
+    it('rejects path-traversal attempts (dotted segments fail the slug guard first)', () => {
+      expect(() => getComponentLlmPath('x', '..')).toThrow(/Invalid component slug/);
+      expect(() => getComponentLlmPath('x', '../../../etc/passwd')).toThrow(
+        /Invalid component slug/
+      );
+    });
+  });
+});