agentleFS
nikzlabsnikzlabs/shipit/.agents/skills/design-language/SKILL.md

design-language

Skill9 starsChanged 18 days agoApache-2.0View on GitHub

ShipIt design language: color tokens, typography, iconography, motion, and multi-theme architecture. Load when working on UI components, styling, theming, or adding new visual elements.

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never use raw Tailwind color classes like bg-gray-950 or text-blue-500 in components — use bg-[var(--color-bg-primary)].

    line 23
  2. Very specific:

    Sizes: Use ICON_SIZE constants from src/client/design-tokens.ts — SM (16px) inline with text, MD (20px) buttons/nav, LG (32px) empty …

    line 79
  3. Distinctive:

    Add it to the table above in this skill

    line 157

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Design Language

ShipIt uses semantic design tokens (CSS custom properties) for all colors. Themes are token overrides applied via a class on <html>. All UI code references tokens — never raw Tailwind color classes.

Concrete color values live in per-theme CSS files under src/client/themes/. Each file defines one theme's token values. src/client/index.css imports them and contains shared rules (animations, scrollbars, syntax highlighting). Theme state is managed by useTheme() in src/client/hooks/useTheme.ts (persisted to localStorage key shipit-theme).

src/client/themes/
  light.css       ← :root { --color-bg-primary: ...; }
  dark.css        ← .dark { --color-bg-primary: ...; }

To add a new theme: create a new CSS file in themes/, import it in index.css, register the name in useTheme(). No component changes needed.

Color Tokens

Never use raw Tailwind color classes like bg-gray-950 or text-blue-500 in components — use bg-[var(--color-bg-primary)].

TokenPurpose
--color-bg-primaryPage/app background
--color-bg-secondarySidebar, secondary panels
--color-bg-tertiaryCards, inputs, code blocks
--color-bg-elevatedDropdowns, modals, popovers
--color-bg-overlayBackdrop behind modals
--color-bg-hoverHover state for interactive surfaces
--color-bg-activeActive/pressed state
--color-text-primaryBody text, headings
--color-text-secondaryDescriptions, timestamps
--color-text-tertiaryPlaceholders, disabled
--color-text-inverseText on filled backgrounds
--color-text-linkClickable text links
--color-border-primaryPanel borders, dividers
--color-border-secondaryInput borders
--color-border-focusFocused input ring
--color-accentPrimary buttons, active tabs
--color-accent-hoverPrimary button hover
--color-accent-textText on accent backgrounds
--color-accent-subtleTinted backgrounds, badges
--color-successConnected, passed, deployed
--color-success-subtleSuccess background
--color-errorFailed, disconnected, destructive
--color-error-subtleError background
--color-warningIn-progress, caution
--color-warning-subtleWarning background
--color-infoInformational, typing
--color-info-subtleInfo background
--color-prPR open/merged indicator
--color-folderFolder icon in file tree
--color-autofixAuto-fix toggle/indicator
--color-context-okContext meter 0–60%
--color-context-midContext meter 60–80%
--color-context-highContext meter 80–90%
--color-context-fullContext meter 90%+
--color-scrollbar-thumbScrollbar thumb
--color-scrollbar-thumb-hoverScrollbar thumb on hover
--font-size-codeMonospace / code block font size
--duration-fastColor transitions, exits
--duration-normalEnter animations, layout shifts
--duration-slowLoading spinners
--ease-defaultDefault easing
--ease-outEnter animations
--ease-inExit animations

Typography

System font stack, no custom web fonts. Body: text-sm, headings: text-lg font-semibold, code: font-mono text-[var(--font-size-code)], small: text-xs.

Iconography — Phosphor Icons

Library: @phosphor-icons/react. All icons use Phosphor — no inline SVGs or Unicode characters.

Sizes: Use ICON_SIZE constants from src/client/design-tokens.ts — SM (16px) inline with text, MD (20px) buttons/nav, LG (32px) empty states, XL (48px) hero.

Weights: "regular" (default), "bold" for emphasis, "fill" for toggle-on states, "duotone" sparingly for illustrations.

The one exception — a scene, not a symbol. A hand-written inline <svg> is allowed only for a bespoke illustration in an empty or onboarding state, where the drawing has to depict a relationship a glyph set cannot: an arrangement of parts (a slot, a container, an arrow between two things), a state (empty, waiting, filled), or a data-driven shape. Composed Phosphor glyphs are the default even for illustrations — reach for this only after trying them. Anything that labels an action, a status, or a row is an icon, and icons are always Phosphor, no exceptions.

An illustration under this exception must still: use only semantic colour tokens (it is drawn in every theme); carry aria-hidden="true" unless it conveys something the adjacent copy does not; scale with its container (max-w-full h-auto, never a fixed width in a resizable pane); and disable any animation under prefers-reduced-motion. Current members of this set: PreviewFrame/PreviewSetupInvite.tsx (empty-preview scene), RocketLaunch.tsx (new-session animation), ContextDial.tsx (data-driven gauge).

The other exception — a mark you quote, not one you draw. A vendor logo is an inline <svg> too, because Phosphor is a set of generic UI symbols and ships no brand marks. Nothing about a logo is a design decision: the shape belongs to its owner, so it is copied verbatim (Simple Icons is CC0 and is where ours come from) rather than approximated with a glyph. A logo must carry aria-hidden="true" — the vendor's name is invariably beside it, and a mark that announces itself makes a screen reader say the name twice.

Colour is the one judgement left, and it is decided by the brand, not by taste. A mark the vendor publishes in black (Anthropic, OpenAI, Vercel, Z.ai) is drawn in currentColor, because a hardcoded #000 disappears on a dark background — this is not a compromise, it is what the mark looks like in each theme. A brand whose colour IS the mark keeps it as a literal hex, checked for legibility on light and dark: Settings/components/LinearCredential.tsx's LinearLogo (#5e6ad2) is the standing example. And where a set of marks is drawn as a column, keep the set consistent rather than colouring one row of it — ServiceLogo.tsx draws all six service marks in currentColor for that reason, since only DeepSeek's is coloured and one blue tile among five grey ones reads as a rendering bug.

This exception is for logos only — it does not license a hand-drawn icon for anything ShipIt owns.

Color: Icons inherit currentColor. Set via parent's text color token:

import { ICON_SIZE } from "../design-tokens.js";

<span className="text-[var(--color-text-secondary)]">
  <GitBranch size={ICON_SIZE.SM} />
</span>

Key mappings (non-obvious or domain-specific):

ConceptIconColor Token
PR openGitPullRequest--color-pr
PR mergedGitMerge--color-pr
PR closedGitPullRequest--color-text-tertiary
SuccessCheckCircle--color-success
ErrorXCircle--color-error
WarningWarning--color-warning
PendingCircleNotchWith animate-spin
FolderFolder / FolderOpen--color-folder
DeployRocket
TrashTrash--color-error (destructive)
External linkArrowSquareOut

Motion

Motion tokens are defined in index.css (shared, not per-theme). Use transition-[color] duration-[var(--duration-fast)] instead of Tailwind's transition-colors to reference the token. Avoid animating layout properties (width, height) unless explicitly resizing.

Do not animate a surface full of text on entry — neither a scale nor a fade. Both move the text of a large panel, in different ways. A scale moves it geometrically: the fade lands first, so the text is readable while the scale still has ~1% to run and every line slides a pixel or two into place. A fade moves it optically: mid-opacity the element is composited on its own layer, where glyphs are antialiased in grayscale, and on the final frame the layer collapses and they re-render with subpixel antialiasing — the geometry never changes, but the eye reads the change in glyph weight as a settle. DialogContent therefore has no entrance animation at all; the overlay's fade carries it. dialog.test.tsx guards this. Small surfaces (tooltip, popover, dropdown menu) keep both effects — near their transform origin, holding a line or two, neither is legible.

UI Primitives

Shared components in src/client/components/ui/ using CVA (class-variance-authority) for variant-based styling. Never duplicate token class strings across components — use these primitives instead.

ComponentFileVariants
Buttonbutton.tsxvariant: primary, secondary, destructive, ghost. size: sm, md, lg
Badgebadge.tsxvariant: default, success, error, warning, info
StatusDotstatus-dot.tsxstatus: success, error, warning, info
Bannerbanner.tsxvariant: error, warning, info, success
Dialogdialog.tsxModal overlay with backdrop
Tooltip / Popover / DropdownMenu / OverflowMenutooltip.tsx, popover.tsx, dropdown-menu.tsx, overflow-menu.tsxFloating surfaces
Tabs / Tabtabs.tsx, tab.tsxTab strips
Avatar, CopyButtonavatar.tsx, copy-button.tsx—

ls src/client/components/ui/ is authoritative if this table lags.

Example usage:

import { Button } from "./ui/button.js";

<Button variant="destructive" size="sm">Delete</Button>

Adding a new primitive

  1. Create src/client/components/ui/<name>.tsx
  2. Define variants with cva() — use only design tokens for colors, motion tokens for transitions
  3. Accept className prop and merge it with CVA output (so consumers can add layout classes like margins)
  4. Forward ref and spread remaining props onto the root element
  5. Export the component and its variant props type
  6. Add it to the table above in this skill

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.