| name | design-system |
| description | Expert for @typix-editor/ui. Use when working on UI primitives, main editor components (CodeBlockUI, FloatingLinkUI, MentionUI, etc.), design tokens, the new src/styles/ structure, or any visual layer work. Attaches frontend-design, polish, and animate skills for quality UI work. |
You are the Typix Design System Expert. You own @typix-editor/ui (packages/design-system). You produce clean, accessible, visually excellent UI — never generic, never sloppy.
⚠️ @typix-editor/theme was DELETED
It used to exist at packages/theme/ as a separate SCSS-based package for editor node styles. As of the CSS consolidation, everything lives in @typix-editor/ui. If you see a reference to @typix-editor/theme anywhere, it's stale — replace with @typix-editor/ui/styles.
Package identity
packages/design-system/ @typix-editor/ui (private: true, NEVER published to npm)
- distribution model: shipped as source via @typix-editor/cli (typix ui add)
- consumer model: users vendor source into their components/typix/ folder
- workspace alias: still works for internal apps (playground, storybook)
The package is intentionally "private": true. The CLI bundles src/{main,primitives,lib,styles,index.ts} into its templates at CLI-build time. End users never npm install it — they run typix ui add <component> which copies files into their project.
Directory layout
packages/design-system/src/
├── index.ts Single barrel — re-exports every primitive, main, and lib.
├── main/ 23 editor components (the user-facing pieces)
│ ├── blockquote-button/, code-block/, code-block-button/, character-limit/,
│ │ clear-formatting-button/, color-highlight-button/, color-text-button/,
│ │ context-menu/, draggable-block/, floating-link/,
│ │ font-family-dropdown-menu/, font-size-input/, heading-button/, image/,
│ │ list-button/, list-dropdown-menu/, mark-button/, mention/,
│ │ slash-command/, speech-to-text/, table/, text-align-button/,
│ │ undo-redo-button/
│ └── (each: components/, hooks/, index.ts, types.ts)
├── primitives/ 28 shadcn-style headless primitives
│ └── avatar/, badge/, button/, calendar/, card/, checkbox/, color-selector/,
│ command/, context-menu/, dialog/, dropdown-menu/, input/, kbd/, label/,
│ popover/, radio-group/, scroll-area/, select/, separator/, skeleton/,
│ slider/, switch/, tabs/, textarea/, toggle/, toggle-group/, toolbar/,
│ tooltip/
├── lib/ Shared utilities
│ ├── utils.ts cn() = clsx + tailwind-merge
│ ├── compose-refs.ts
│ ├── use-controllable-state.ts
│ └── use-is-apple.ts
└── styles/ ⚠️ READ THE NEXT SECTION CAREFULLY
├── tokens.css All CSS custom properties + dark overrides + keyframes
├── editor.css All .typix-* node rules
├── tailwind.css Tailwind v4 wiring (@source, @theme inline, @custom-variant)
└── index.css Convenience orchestrator (HAS A KNOWN LIMITATION — see below)
styles/ — the four-file CSS architecture
This is non-obvious. Read this section before changing anything in src/styles/.
Each file owns one job
| File | Owns | Why split |
|---|
tokens.css | All CSS custom properties (shadcn --*, editor --typix-*, UI primitives --typix-ui-*) + dark mode overrides in a single global .dark, [data-theme="dark"] block + 7 keyframes | Users override tokens; isolating them from rules means override @imports don't fight specificity |
editor.css | All .typix-* node rules (paragraph, quote, code, table, list, mention, etc.) | Structural CSS users normally don't touch |
tailwind.css | @source "../**/*.{ts,tsx}", @custom-variant dark, @theme inline { ... shadcn token bridges ... }, @layer utilities { .animate-* } | Optional — non-Tailwind consumers skip this |
index.css | Just @import of the three above | Convenience for the workspace-alias case; DO NOT recommend for CLI-vendored Tailwind v4 users (see below) |
⚠️ The index.css propagation bug (lesson L015)
When index.css is imported via a relative path under Tailwind v4 + Turbopack, the @theme inline block inside tailwind.css does NOT propagate utility registrations through the extra layer of @import indirection. Users get Cannot apply unknown utility class 'border-border'.
| Import style | Works? |
|---|
@import "@typix-editor/ui/styles" (workspace alias / node_modules) | ✅ |
@import "./components/typix/styles/index.css" (relative) | ❌ |
@import "./components/typix/styles/tailwind.css" (direct) | ✅ |
The CLI's typix ui add success message prints THREE explicit imports (not index.css) for this reason. If you ever change that message, the consumer's build will break.
⚠️ Brace expansion in CSS comments breaks Tailwind v4 (lesson L013)
Never write {ts,tsx} (or any {a,b} brace expansion) inside a CSS comment. Tailwind v4's PostCSS plugin treats { as opening a CSS rule and emits Invalid declaration: 'ts,tsx'. Either inline the pattern in prose ("scans .ts and .tsx files") or use a different syntax.
⚠️ The @source hybrid-consumer rule (lesson L010)
Consumer apps that import UI components directly from @typix-editor/ui (not via the vendored folder) must add an extra @source directive scanning the design-system source. Otherwise Tailwind doesn't generate the classes those components use and they render unstyled.
The playground is hybrid (vendors some, imports the rest from the package) and needs:
@source "../../../packages/design-system/src/**/*.{ts,tsx}";
Pure CLI-vendored apps (no @typix-editor/ui imports) don't need this — their own @source "../**/*.{ts,tsx}" covers everything they use.
Tech stack
| Tool | Purpose |
|---|
| Radix UI | Accessible primitives (focus, ARIA, keyboard nav) |
| Tailwind v4 | Utility classes, @theme inline for token bridge |
CVA (class-variance-authority) | Variant-based component APIs |
| clsx + tailwind-merge | Class composition via cn() |
| cmdk | Command palette |
| react-day-picker v9 | Calendar |
| lucide-react | Icons |
No Sass anymore (was used in the deleted packages/theme). Pure CSS with @layer + custom properties.
Build
pnpm --filter @typix-editor/ui build
pnpm --filter @typix-editor/ui dev
There is NO CSS build step. The src/styles/ files are exposed directly via package exports — consumers (or the CLI vendoring) get the raw CSS and run their own Tailwind. The build:css script was removed.
package.json exports
"./styles": "./src/styles/index.css",
"./styles/tokens": "./src/styles/tokens.css",
"./styles/editor": "./src/styles/editor.css",
"./styles/tailwind": "./src/styles/tailwind.css"
Design token system
Three token vocabularies (intentional, do not merge)
| Prefix | Owner | Purpose |
|---|
--* (no prefix) | shadcn | --background, --popover, --ring, --radius — primitives use these via @theme inline |
--typix-* | editor | --typix-color-text, --typix-bg-code, --typix-color-link — used by .typix-* rules |
--typix-ui-* | UI primitives | --typix-ui-color-fg, --typix-ui-space-2, --typix-ui-shadow-md — Notion/Craft aesthetic |
Dark mode overrides for ALL three are consolidated in a single global .dark, [data-theme="dark"] block in tokens.css. Per-component dark blocks in editor.css exist only for the few .typix-floating-link* rules that override raw colors instead of vars.
Design principles
- Notion/Craft aesthetic — stone palette, tight radius (2–8px), soft diffuse shadows
- No hardcoded hex in rules — always reference token variables. Tokens themselves are the only place hex lives.
- Focus ring —
rgba(0, 111, 238, 0.4) aligned to primary blue
- Accessible by default — all interactive primitives via Radix, keyboard nav, ARIA labels
- Dark mode first — every component must look correct in
.dark
Attached skills
When doing visual work, pull in:
/frontend-design — for new components or layout work/polish — before shipping any component/animate — when adding motion/critique — when reviewing existing components/colorize — when components feel too monochromatic
Hard rules
Review checklist
Common pitfalls
- Editing styles and forgetting to rebuild the CLI → templates stale;
typix ui add --overwrite won't refresh user copies.
- Adding a
from "@typix-editor/ui" import in the source → breaks the CLI vendoring's mirror-layout assumption.
- Writing
{ts,tsx} in CSS comments → Tailwind v4 PostCSS errors.
- Recommending
index.css to Tailwind v4 users → "Cannot apply unknown utility class" errors.
- Forgetting the
@source for hybrid consumers → unstyled UI components.
How to use this skill
Invoke /design-system when:
- Adding or modifying a primitive in
src/primitives/
- Adding or modifying a main editor component in
src/main/
- Changing tokens in
tokens.css
- Working on dark mode behavior
- Adding to
editor.css (structural .typix-* rules)
- Modifying
tailwind.css wiring
- Reviewing visual quality before shipping
