---
name: design-system
description: Use when building, styling, or reviewing ANY user-facing UI in an m7kni / rknightion / BroTEK product — web app screens, marketing pages, docs styling, or SwiftUI surfaces. Loads the m7kni design system rules: tokens-only colour, component usage, page patterns, voice, and the anti-slop ban list.
---

# m7kni design system

One system for every product. The law lives in this repo (m7kni/design-system); this skill tells
you how to apply it. When this repo is not checked out locally, read the same files from GitHub.

## Before writing any UI

1. Read `FOUNDATIONS.md` — the frozen decisions. Do not re-litigate them.
2. Read the pattern doc for the page shape you are building (`docs/patterns/app-shell.md`,
   `docs/patterns/list-page.md`, more as they land). If no pattern fits, say so and propose one —
   do not improvise a new page anatomy silently.
3. Read `docs/voice.md` before writing any copy. Use glossary terms exactly.
4. `DESIGN.md` is the machine summary (generated from tokens — trust it over memory).

## Hard rules

- **Colour comes from semantic tokens only** — `--color-*` variables from `@m7kni/tokens`
  (`packages/tokens/dist/tokens.css`), or the Tailwind utilities bridged in
  `packages/ui/src/theme.css` (`bg-canvas`, `text-ink`, `text-ok`, `bg-primary`, …). Never a hex
  literal, a raw Tailwind palette class (`bg-blue-500`), or an arbitrary value (`bg-[#123]`).
- **Components come from `@m7kni/ui`** — copy them via the shadcn registry
  (`packages/ui/public/r/<name>.json`), don't rebuild them. Base UI primitives, Phosphor icons
  (regular weight) only.
- **Both themes, always.** Light is default; dark re-points the same variables via
  `[data-theme="dark"]`. Never use Tailwind `dark:` against the OS — it is bound to the attribute.
- **Status = shape + word (+ note)**, never colour alone. Use `StatusWord`. One status per row.
- **Meters** use `Meter` — ink-derived track, zero renders as a dim 0.
- **AA is gated**: any token change must pass `just check` (contrast script, both themes).

## Ban list (do not generate)

Purple→cyan gradients · glassmorphism as default surface · Inter/Geist-as-unchosen-default ·
grey-bordered cards as the universal container · three-column icon-feature grids · centred hero +
logo row · identical sidebar/topbar/breadcrumb/card-grid shells · emoji as icons · mixed icon sets
· bounce/scale hovers · over-saturated accents · jade green or teal-cyan-on-dark accents.

## Verification before claiming done

Render the change in BOTH themes and check: text on every background it sits on; interactive
elements use the accent and nothing else does; table furniture survives hover/selected rows;
`prefers-reduced-motion` collapses animation. For system changes, run `just check` in the
design-system repo and show the output.