# @cf/ui design rules The rules for building with @cf/ui, Connor Forsyth's component system. Rules are MUST, SHOULD or MAY, in the RFC 2119 sense. Docs: https://ds.connorforsyth.co. MCP: https://ds.connorforsyth.co/api/mcp. Install the registry once, then add components by name: ```json { "registries": { "@cf": "https://ds.connorforsyth.co/r/{name}.json" } } ``` ```sh bunx shadcn@latest add @cf/button ``` ## Foundations ### Purpose What @cf/ui is, where it comes from, and how to use it in another project. - **SHOULD** `install-through-registry`: Add components with `bunx shadcn@latest add @cf/` so the `@cf/theme` item and any sibling components come with them. _Every component lists `@cf/theme` as a registry dependency, and without it the semantic utilities resolve to nothing._ - **MUST** `bring-your-own-fonts`: Set the typeface on the page yourself; do not expect the registry to install KAG, Rodney or any other font. _KAG and Rodney are licensed, so they stay with the site._ - **SHOULD** `read-design-md`: Run `bunx shadcn@latest add @cf/design` in a consuming repo so the agents working there read the same rules as this document. ## What this is @cf/ui is the set of components and tokens that my personal site actually runs on. It is not a separate library that the site consumes after the fact: the components in `packages/ui/src/components` are the ones rendering the notes editor, the chat panel and the CV, and the site imports `@cf/ui/styles/theme.css` for its palette, the same tokens `@cf/theme` writes into anyone else's stylesheet. When I fix a component for the site, the registry gets the fix. I'm building it in public. Some of it is tidy and some of it is still carrying stock shadcn classes I haven't reviewed yet; where I know about a gap I say so in the relevant page rather than pretend it isn't there. ## How to use it There are three ways in, all generated from the same source by `design/compile.ts`: - **The registry.** Point shadcn at `https://ds.connorforsyth.co/r/{name}.json` under the `@cf` namespace, then `bunx shadcn@latest add @cf/button`. You get the source file copied into your repo, plus the theme and any components it imports. - **DESIGN.md.** `bunx shadcn@latest add @cf/design` writes the rules on this site into your repo as `DESIGN.md`, so a coding agent can follow them without visiting the docs. - **MCP.** `https://ds.connorforsyth.co/api/mcp` answers questions about the components, tokens and rules from the same compiled knowledge. ## What's not included Fonts are not part of the registry. The components are font-agnostic and inherit whatever the page sets. Breakpoints, the site's brand blue, search highlight colours and utilities like `touch-target` also live with the site in `styles/globals.css`, not in the theme. If a component needs one of those to look right, that is a bug in the component. ### Principles The handful of ideas the code already follows, written down so new work follows them too. - **MUST** `semantic-tokens-only`: Colour components with semantic utilities such as `bg-primary`, `text-muted-foreground` and `border-border`, never raw palette values like `bg-gray-3` or hex codes. - **MUST** `inherit-typeface`: Do not set a `font-family` in a component; let it inherit from the page, with `font-mono` in `Kbd` as the only exception. - **SHOULD** `subtract-dont-adapt`: Below `md`, remove affordances that only exist for a keyboard or pointer (keycap hints, hover tooltips, shortcut rows) instead of shrinking them or inventing touch equivalents. - **SHOULD** `comment-the-why`: When a component departs from the stock shadcn version, leave a comment in the source saying why. _The source is what gets copied into your repo, so the reasoning has to travel with it._ ## Semantic tokens over raw values Components ask for a role, not a colour. `bg-primary` means "the strongest fill", and `theme.css` decides that is Radix `gray-12` in light mode. That is what lets dark mode, and anyone else's palette, work without touching component code. ## Inherit type, don't own it The site sets its typeface on `body`. Components set sizes and weights (`text-sm`, `font-medium`) and nothing else, so they look native wherever they're dropped. The one exception is `Kbd`, which uses `font-mono` because a keycap should read as a key. ## Subtract, don't adapt On small screens I remove things rather than translate them. A tooltip that explains a shortcut has nothing to offer a phone, so it goes. What remains still gets touch treatment: 16px inputs so iOS doesn't zoom, taller menu items below `md`, and `touch-target` on isolated small controls. ## The source is the documentation This registry copies source, so the source has to explain itself. `button.tsx` says why hit-area expansion is opt-in; `switch.tsx` says why the track uses foreground and background instead of `--input`; `theme.css` says why destructive skips Radix step 9. These pages summarise those comments; when they disagree, the code is right and this page is stale. ## Honest about gaps Some components still carry stock shadcn classes I haven't reconciled, such as `dark:` opacity tweaks and two different focus ring weights. I'd rather list those than hide them. ### Styling How components are styled with Tailwind v4 and semantic utilities, and how to change them. - **MUST** `merge-with-cn`: Accept a `className` prop and merge it last with `cn(...)` so callers can override any class. - **SHOULD** `no-dark-colour-overrides`: Do not add `dark:` colour classes to a component; change or add a token in `theme.css` so both modes switch together. _Tokens already resolve per mode under `.dark`, so a `dark:` class is a second source of truth._ - **SHOULD** `data-slot-on-parts`: Give each exported part a `data-slot` attribute (for example `data-slot="dialog-content"`) and style relationships between parts against it rather than against class names. - **SHOULD** `extend-with-classname-first`: Change a component for one use with `className`; edit the copied source only when the change should apply everywhere in your project. ## Tailwind v4 and the theme Components are plain Tailwind v4 class strings. `theme.css` maps each token into the `@theme` block (`--color-primary: var(--primary)`), so utilities like `bg-primary`, `border-input` and `ring-ring` exist, and the radius scale (`rounded-lg`, `rounded-md`, `rounded-sm`) is derived from one `--radius`. In another repo, `bunx shadcn@latest add @cf/theme` writes those tokens into your own global stylesheet (the Radix imports, `:root`, `.dark` and the `@theme` map), replacing the palette `shadcn init` left there. Keep `shadcn/tailwind.css` imported too: it supplies the `data-open`, `data-closed` and similar state variants the components use. Variants are written with `cva`, as in `buttonVariants`, and every component passes its classes through `cn` from the `cn` package with the caller's `className` last. That is what makes ` ``` ### Carousel `@cf/carousel`: A horizontally or vertically scrolling set of slides on Embla, with previous and next buttons and arrow-key support. Install: `bunx shadcn@latest add @cf/carousel` · Docs: https://ds.connorforsyth.co/components/carousel - **MUST** `items-inside-content`: Wrap every slide in `CarouselItem` inside `CarouselContent`, and keep `CarouselPrevious` and `CarouselNext` inside the `Carousel` root, which provides their context. - **MUST** `position-the-buttons`: Place `CarouselPrevious` and `CarouselNext` yourself, because they have no positioning classes of their own. - **SHOULD** `constrain-the-root`: Put a max width on `Carousel`, not on `CarouselContent`. _The overflow-hidden wrapper around the track is what clips, so constraining only the track lets the neighbouring slide spill into view._ - **SHOULD** `show-position`: Show where the person is (for example Slide 2 of 5) using the `setApi` callback, since the component has no dots or counter of its own. shadcn's carousel over `embla-carousel-react`, with Phosphor arrows. The buttons disable at each end, and Left and Right arrow keys move between slides from anywhere inside the root. It's the case-study carousel in MDX, with the buttons and a Slide n of m counter in a row above the track. A few upstream rough edges are still in it: arrow keys are Left and Right even when `orientation="vertical"`, the `reInit` listener is never removed, and it still uses `forwardRef`. ```tsx import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, } from "@/components/ui/carousel";

Slide {current} of {count}

{slides.map((slide) => ( {slide.node} ))} ``` ### Dialog `@cf/dialog`: A modal window for a focused task, like a short form or a media viewer, that the person can dismiss freely. Install: `bunx shadcn@latest add @cf/dialog` · Docs: https://ds.connorforsyth.co/components/dialog - **MUST** `title-or-label`: Give every `DialogContent` a `DialogTitle`, or an `aria-label` when the content has no heading of its own (as the chat media viewer does). - **MUST** `alert-dialog-for-confirmation`: Use `AlertDialog`, not Dialog, to confirm a destructive or irreversible action. _An alert dialog isn't dismissed by clicking outside, so a confirmation can't be skipped by accident._ - **SHOULD** `one-close-button`: Keep the default close button (`showCloseButton` is true), or set `showCloseButton={false}` and render your own `DialogClose`; don't end up with two or none. - **SHOULD** `footer-for-actions`: Put the actions in `DialogFooter`, primary last in source order, so they stack with the primary on top below `sm` and sit right-aligned above it. Base UI's `Dialog`. The popup is capped at `100svh - 2rem` and scrolls, because without that anything taller than the screen got clipped with no way to reach the rest of it. It's `max-w-sm` from `sm` up, so wider content (the media viewer uses `sm:max-w-3xl`) has to say so. `DialogFooter` bleeds to the popup's edges with a muted band, and can render its own outline Close button with `showCloseButton`. The note dialogs (add video, image alt text, section settings) all follow header, fields, footer. ```tsx import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, } from "@/components/ui/dialog"; Add video Paste a link to an mp4. ``` ### Dropdown Menu `@cf/dropdown-menu`: A list of actions or toggles opened from a trigger, with groups, labels, submenus, checkbox and radio items. Install: `bunx shadcn@latest add @cf/dropdown-menu` · Docs: https://ds.connorforsyth.co/controls/dropdown-menu - **MUST** `destructive-item-variant`: Mark delete and discard items with `variant="destructive"` on `DropdownMenuItem`, and put them in their own `DropdownMenuGroup` after a `DropdownMenuSeparator`. - **SHOULD** `confirm-irreversible`: Open an `AlertDialog` from a destructive item when the action can't be undone, rather than acting on the click. - **MUST** `labels-inside-groups`: Put `DropdownMenuLabel` inside a `DropdownMenuGroup`; it's Base UI's group label and needs a group to belong to. - **SHOULD** `shortcuts-hidden-on-touch`: Hide `DropdownMenuShortcut` below `md` (`hidden md:inline`) when you use it; the component doesn't do that for you. _Shortcut hints are keyboard affordances, and the site removes those on touch screens._ - **SHOULD** `select-for-values`: Use `Select` for picking a value that the trigger should then display, and keep the menu for actions and toggles. Base UI's `Menu` under shadcn's names. Rows are 16px text with extra padding below `md`, the same as select items, so they're tappable without a separate mobile menu. The two indicators sit on different sides and that's not fully resolved. The radio tick is on the right, where an item's state belongs, and it's a tick rather than a dot because a dot at that size reads as a stray mark. The checkbox tick is still on the left with a `pl-8` inset. Both carry `data-slot="menu-item-indicator"` so a row that shows its state another way, like the notes visibility rows with a `Switch`, can hide the tick. ```tsx import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, } from "@/components/ui/dropdown-menu"; }> Rename setDeleting(true)} variant="destructive"> Delete ``` ### Editor `@cf/editor`: The chrome for a Tiptap editor, meaning a formatting menu over the selection and a slash menu on empty lines, with no fixed toolbar. Install: `bunx shadcn@latest add @cf/editor` · Docs: https://ds.connorforsyth.co/blocks/editor - **MUST** `needs-starter-kit`: Use these with an editor that has StarterKit and TaskList (`@tiptap/extension-list`) loaded; `TOOLBAR_ACTIONS` call their commands. - **SHOULD** `no-fixed-toolbar`: Put `SelectionMenu` and `SlashMenu` on the editor instead of a fixed toolbar row; formatting shows up where you're already looking. - **SHOULD** `word-labels`: Label a new `ToolbarAction` with a word (`label: "Quote"`), not a glyph, and give it a `title` for the accessible name. - **MUST** `keep-selection`: Give any custom menu button `onMouseDown={(event) => event.preventDefault()}`, as `ActionButtons` does, so clicking it doesn't take the selection away. - **MAY** `extra-marks-need-extensions`: Leave the Highlight action in `TOOLBAR_ACTIONS` only if the editor has a mark named `highlight`; otherwise filter it out. This is the part of the notes editor on connorforsyth.co that isn't about notes. There's no toolbar. Select text and `SelectionMenu` floats over it with Bold, Italic, Code, Highlight, Heading, Quote and Link. Type `/` on an empty line and `SlashMenu` offers the block actions; keep typing to filter them, and use the arrows and Enter to pick one. Both work from one list of `ToolbarAction`s, so an app adds its own (the notes editor adds images and note links) by passing a longer array. The menus are labelled with words rather than icons, because nothing should need decoding. On a phone the selection menu goes below the selection instead of above it, since above is where iOS draws its own Copy and Look Up bar, and its buttons get taller. The row scrolls sideways instead of wrapping over what you're writing. What isn't here is the editor itself: extensions, markdown in and out, autosave, uploads. Those differ per use, and on the site they're wired to notes. I've marked it beta because the actions assume StarterKit's command names and I haven't made that pluggable. ```tsx "use client"; import { TaskItem, TaskList } from "@tiptap/extension-list"; import { EditorContent, useEditor } from "@tiptap/react"; import StarterKit from "@tiptap/starter-kit"; import { BLOCK_ACTIONS, SelectionMenu, SlashMenu } from "@/components/ui/editor"; const editor = useEditor({ extensions: [StarterKit, TaskList, TaskItem], immediatelyRender: false }); {editor && } {editor && } ``` ### Field `@cf/field`: The layout set for form fields, labels, descriptions, errors, fieldsets and groups, with vertical, horizontal and responsive orientations. Install: `bunx shadcn@latest add @cf/field` · Docs: https://ds.connorforsyth.co/controls/field - **MUST** `label-with-html-for`: Give every `Field` a `FieldLabel` with `htmlFor` matching the control's `id`; `FieldTitle` is a visual heading and doesn't name anything. - **MUST** `invalid-on-both`: When a field is invalid, set `data-invalid` on `Field` and `aria-invalid` on the control together, and put the message in `FieldError`. _`data-invalid` only colours the group; `aria-invalid` is what assistive tech and the control's own styles read._ - **MUST** `responsive-needs-group`: Wrap fields in `FieldGroup` when using `orientation="responsive"`, because it switches on the `@container/field-group` query. - **SHOULD** `fieldset-for-choice-groups`: Use `FieldSet` with a `FieldLegend` for a group of radios, checkboxes or switches that answer one question, not a `FieldGroup` with a heading. - **SHOULD** `horizontal-for-toggles`: Use `orientation="horizontal"` for a Switch or checkbox beside its label, with the text in `FieldContent`. Stock shadcn `base-nova`, built from plain elements rather than Base UI's `Field`, so it doesn't track validity itself. `Field` is a `role="group"` div that styles its children through `data-slot` selectors, `FieldLabel` is `Label` with extra states (a label that wraps a whole `Field` becomes a selectable card), and `FieldError` takes either children or an `errors` array, dropping duplicate messages. This is what the contact form and the note dialogs use. `form` is an older Base UI wrapper with the same export names; don't mix the two in one file. One quirk carried over from upstream: `FieldTitle` also sets `data-slot="field-label"`. ```tsx import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"; import { Input } from "@/components/ui/input"; Email Only used to reply to you. ``` ### Form `@cf/form`: A thin wrapper over Base UI's `Field` (root, label, description, error) for fields that want Base UI's own validation state. Install: `bunx shadcn@latest add @cf/form` · Docs: https://ds.connorforsyth.co/controls/form - **MUST** `dont-mix-with-field`: Don't import `Field`, `FieldLabel`, `FieldDescription` or `FieldError` from both `form` and `field` in the same file; they share names but are different components. - **SHOULD** `prefer-field-for-layout`: Reach for the `field` component for new forms, and use `form` only where you want Base UI's `Field.Root` validity handling. - **MUST** `explicit-html-for`: Set `htmlFor` on `FieldLabel` and a matching `id` on the input, because `Input` is a plain `` and not Base UI's `Field.Control`, so Base UI can't wire the label up itself. - **SHOULD** `error-needs-validity`: Know that this `FieldError` renders from Base UI's validity state, which a plain `Input` doesn't report; show custom error text yourself, as the access form does, or give `FieldError` a `match` to force it. Passing `invalid` to `Field` does not show it. This is the older of the two field sets, and it overlaps with `field`. `Field` here is Base UI's `Field.Root` exported as is; the label, description and error parts only add type styles. Only the access form uses it, and even there the input is the plain `Input`, so the form sets `htmlFor`, `aria-invalid` and `data-invalid` by hand and writes its own error text. I'm keeping it while that form is the only caller. The honest direction is to fold it into `field` or wire `Input` up as a `Field.Control`, and until one of those happens I've marked it beta. ```tsx import { Field, FieldLabel } from "@/components/ui/form"; import { Input } from "@/components/ui/input"; Access code ``` ### Input `@cf/input`: A single-line text field, 44px tall and 16px type on touch screens, shrinking to 36px and 14px at `md`. Install: `bunx shadcn@latest add @cf/input` · Docs: https://ds.connorforsyth.co/controls/input - **MUST** `label-every-input`: Pair every Input with a `FieldLabel` or `Label` whose `htmlFor` matches the input's `id`, or give it an `aria-label` when there's no visible label. - **MUST** `keep-16px-on-touch`: Don't override the text size below `md` to anything under 16px; if you change it, keep the `text-base md:text-sm` pairing. _iOS zooms the page into any field set smaller than 16px and never zooms back out._ - **MUST** `use-group-control-in-groups`: Inside an `InputGroup`, use `InputGroupInput` instead of Input. _The group's focus and invalid rings key off `data-slot="input-group-control"`, which only InputGroupInput sets._ - **SHOULD** `invalid-needs-your-own-styles`: When a value is invalid, set `aria-invalid` on the input and `data-invalid` on its `Field`, and know that Input has no `aria-invalid` styles of its own yet. A plain ``, not a Base UI part. The 16px and 44px sizing on touch screens is the whole point of it: iOS zooms into anything smaller than 16px and a 36px field is awkward to hit, so both shrink back to the desktop size at `md`. It's older than the rest of the set and it shows. It uses `forwardRef`, `rounded-md` and a `ring-1` focus ring, where Textarea uses `rounded-lg`, a `ring-3` focus ring and `aria-invalid` styles. The access form paints its own error border because of that gap. Bringing Input in line with Textarea is on the list. ```tsx import { Input } from "@/components/ui/input"; ``` ### Input Group `@cf/input-group`: A bordered shell that joins an input or textarea with addons, buttons and text, sharing one focus ring. Install: `bunx shadcn@latest add @cf/input-group` · Docs: https://ds.connorforsyth.co/controls/input-group - **MUST** `use-group-controls`: Put `InputGroupInput` or `InputGroupTextarea` inside the group, never a bare `Input` or `Textarea`. _The shared focus and invalid rings watch for `data-slot="input-group-control"`, which only the group's own controls set._ - **MUST** `buttons-in-addons`: Use `InputGroupButton` for buttons inside an `InputGroupAddon`, and pass `type="submit"` explicitly for a send button, since it defaults to `type="button"`. - **MUST** `icon-buttons-named`: Give every icon-only `InputGroupButton` (`size="icon-xs"` or `size="icon-sm"`) an `aria-label`. - **SHOULD** `block-align-for-toolbars`: Use `align="block-start"` or `align="block-end"` on `InputGroupAddon` for rows above or below a textarea, and the `inline-*` values for prefixes and suffixes on a single-line input. Stock shadcn `base-nova`. Clicking an addon focuses the control, unless the click lands on a button. The chat composer is the one real use: a quote strip in a `block-start` addon, the `InputGroupTextarea`, and send and stop buttons in a `block-end` addon. The group is `h-8`, which doesn't agree with `InputGroupInput`: it inherits Input's `h-11` below `md`, so a single-line group will overflow on touch screens until one of them gives. I've only used it with a textarea so far, where the group goes `h-auto`. Icons also follow a different convention here: `InputGroupButton` sizes bare `svg` children rather than `data-icon` ones. ```tsx import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupTextarea, } from "@/components/ui/input-group"; ``` ### Kbd `@cf/kbd`: A keycap for showing a keyboard shortcut, usually inside a tooltip or beside a menu row. Install: `bunx shadcn@latest add @cf/kbd` · Docs: https://ds.connorforsyth.co/controls/kbd - **MUST** `hide-below-md`: Hide Kbd below `md` (wrap it in `hidden md:flex`, or show it only inside a `TooltipContent`, which touch never opens); don't adapt it for touch. _A keycap hint is a keyboard-and-pointer affordance, and on a phone it's noise._ - **SHOULD** `declare-the-shortcut`: Put `aria-keyshortcuts` on the control the shortcut triggers; Kbd is visual only. - **SHOULD** `one-key-per-cap`: Render one Kbd per key for chords, rather than one Kbd holding `⌘K`. - **SHOULD** `no-background-override-in-tooltips`: Leave Kbd's background alone inside `TooltipContent`; it switches to `bg-background/20` there by itself. A `` with `data-slot="kbd"`. Inside a tooltip the ground is the foreground colour, so the key lifts off it with `bg-background/20` instead of the usual `bg-foreground/10`, and the tooltip tightens its own right padding when it contains one. Following the site's mobile rule, I remove shortcut hints below `md` rather than finding a touch equivalent. The notes sidebar wraps its keys in `hidden md:flex`, and the sidebar toggle only shows its `[` inside a tooltip. ```tsx import { Kbd } from "@/components/ui/kbd"; Hide the sidebar [ ``` ### Label `@cf/label`: A styled `