Skillshare UI Design System

Enforce the skillshare design system across the two frontends. $ARGUMENTS is the file or area being worked on.

Before acting, run python3 scripts/ai-context.py frontend. That topic and the CSS/source files it identifies are the source of truth; this skill retains the component catalog and visual QA checklist.

This file names tokens and classes and says when to use them. It does not copy their values. Colours, radii, fonts and shadows change; read them from the CSS when you need one.

UI Dashboard (ui/)

Reference pages: ui/src/pages/TargetsPage.tsx (list page), ui/src/pages/HubPage.tsx (tabs), ui/src/pages/ResourcesPage.tsx (list + tiles + bulk toolbar).

Design rules and the reasoning behind them: references/STYLE_GUIDE.md.

Two styles, two modes

Style and mode are independent, so every screen has four looks.

Set by ui/src/context/ThemeContext.tsx, switched in ThemePopover.tsx. ?theme=clean|playful|dark|light in the URL forces one, which is handy for screenshots.

All four looks come from CSS variables alone. A page that uses only tokens and ss-* classes gets all four for free; a hardcoded colour, radius or shadow breaks three of them.

• Clean: system font, 1px hairlines, soft shadows, ink-coloured primary button.
• Playful: Kalam headings, 2px ink borders, hard offset shadows, dashed separators, yellow primary, pastel accents, dot-grid background, sticky-note tiles.
• Style-only markup: .ss-only-clean / .ss-only-playful (Dashboard shows a count strip in Clean and a pin board in Playful).

Design tokens

Defined per look at the top of ui/src/components.css. ui/src/index.css exposes them to Tailwind through @theme inline, so text-ink-2, bg-surface, border-line all follow the active look.

Tailwind names: bg side surface sunken ink ink-2 ink-3 line line-2 line-soft sel pri on-pri ok warn bad (with -bg) and link / link-bg for --accent.

Legacy names: pencil, pencil-light, paper, paper-warm, muted, muted-dark, success, warning, danger, blue, info, accent still resolve as aliases for markup not yet migrated. Do not use them in new code. When you touch a line that has one, replace it:

ui/src/design.ts (radius, shadows, palette) forwards to the same variables, for inline styles only.

The ss-* classes

All in @layer components in ui/src/components.css. List what exists today:

grep -o '\.ss-[a-z0-9-]*' ui/src/components.css | sort -u

State and variant are short modifier classes on the same element: .on (selected or checked), .sel (selected row or tile), .ok .warn .bad .inf (tone), .sm .lg (size).

Tailwind utilities are for layout inside these (flex, gap-*, min-w-0, w-[92px], truncate). Colour, border, radius and shadow come from ss-* classes or token utilities.

Cascade gotcha: the ss-* classes sit in @layer components, so a Tailwind utility on the same element always wins, whatever the selector specificity. Do not put mb-* on something .ss-wrap already spaces. To override an ss-* property from markup, use the Tailwind important prefix, as in className="ss-r link !min-h-[56px]".

Page structure

<div className="ss-wrap animate-fade-in">
  <PageHeader title={t('x.title')} subtitle={t('x.subtitle')} actions={<>...</>} />

  {/* optional: tabs, or tabs with controls on the right */}
  <nav className="ss-tabs" aria-label={t('x.title')}>
    <button type="button" className={on ? 'on' : ''} aria-current={on}>...</button>
  </nav>

  {error && <div className="ss-note bad"><span className="flex-1">{error.message}</span></div>}

  {empty ? (
    <EmptyState icon={SomeIcon} title="..." description="..." action={...} />
  ) : (
    <div className="ss-list">
      <div className="ss-lh">{/* column labels; widths match the row cells */}</div>
      <Link to="..." className="ss-r link">
        <span className="ss-cat skill"><Puzzle size={16} /></span>
        <span className="nm m min-w-0 flex-1 truncate">name</span>
        <span className="w-[92px] shrink-0"><span className="ss-tag">merge</span></span>
        <span className="ss-st ok">synced</span>
      </Link>
    </div>
  )}

  {/* a second section */}
  <section>
    <div className="ss-sec"><h2>Title</h2><span className="ss-cnt">12</span></div>
    <div className="ss-list">...</div>
  </section>

  {/* dialogs last; DialogShell portals to body */}
</div>

• .ss-wrap spaces its children with a 28px gap. Do not add space-y-* or margins between them.
• A page that is one child of a wider layout, without .ss-wrap, still gets header spacing from .ss-pgh.
• PageHeader has no icon (the icon prop is deprecated); do not pass it. Use backTo for a sub-page of a nav item, crumbs for deeper trails, mono when the title is a resource name.
• A sub-page reached from a nav item keeps that item lit through also in the Layout.tsx nav definition (Skills stays active on /hubs).

Components

Shared components in ui/src/components/ wrap the ss-* classes. Use the component when one exists; write the class directly for things that have none (.ss-list rows, .ss-note, .ss-tabs, .ss-st, .ss-tag, .ss-kv).

Feature folders (audit/, config/, git/, hub/, mcp/, plugins/, skill-editor/, sync/, targets/, tour/) hold page-specific pieces.

Icons

lucide-react only. 14–16px inline, 16px inside .ss-cat, 24px in EmptyState. Stroke width comes from --isw; do not set strokeWidth, except the check mark inside .ss-chk. One icon per concept across the app: check Layout.tsx and neighbouring pages before picking one.

Data fetching

const { data, error, isPending } = useQuery({
  queryKey: queryKeys.someKey,
  queryFn: () => api.someEndpoint(),
  staleTime: staleTimes.someCategory,
});
if (isPending) return <PageSkeleton />;

Keys in ui/src/lib/queryKeys.ts, client in ui/src/api/client.ts, useAppContext() gives { isProjectMode, projectRoot }. Every user-visible string goes through useT(); status, mode and kind labels (merge, linked, skill) stay in English.

Verifying a change

Run the dev server inside the devcontainer with the ui command, never on the host. There Vite listens on :45173 (make ui-dev on a host with Go uses :5173). Screenshot the page in all four looks, at desktop width only: ?theme=clean, ?theme=playful, then each in dark. Look at the screenshots before reporting done. Do not run prettier in ui/; it has no config and rewrites whole files.

Website (website/)

Two separate treatments share one palette in website/src/css/custom.css.

• Fonts: IBM Plex Sans body, Inter headings, JetBrains Mono code. Kalam appears on the homepage only.
• Palette variables keep the --color-pencil / --color-paper / --color-postit names here. That is current for the website; only the dashboard moved to --ink / --bg.
• --radius-wobbly* and the hard --shadow-* are defined globally but belong to the homepage modules. Do not apply them to docs chrome.
• Dark mode swaps the blue primary for amber. Check both modes.
• Docs chrome is styled by overriding Docusaurus classes (.button--primary, .menu__link--active, .admonition, .table-of-contents, .target-badge). Each block in custom.css has a titled banner comment; find the block, edit it there.
• Homepage sections are local components in index.tsx (HeroSection, StringBoard, PinList, SyncTerminal, InstallTabs, FourMovesSection, FeatureMapTeaser, CtaSection), styled from the CSS module.
• Mermaid diagrams use the global handDrawn config in docusaurus.config.ts: labels of one or two lines, <br/> for line breaks, and verify with a screenshot.
• Docs are English only. ~ inside an HTML <code> in MDX must be written ~.

Anti-patterns

Checklist

• Root is .ss-wrap animate-fade-in; PageHeader first, without icon
• No hardcoded colours, radii or shadows; no legacy token names added
• Shared components used where they exist; lists are .ss-list / .ss-r
• Errors are .ss-note bad, empty states are EmptyState, destructive actions go through ConfirmDialog
• Icon-only buttons have an accessible name; click targets are 24px or more
• Strings go through useT(); new shortcuts are added to useGlobalShortcuts.ts
• Screenshots checked in Clean and Playful, light and dark