---
version: alpha
name: SCUI
description: Seed Club's shadcn registry design system for building quiet, dense, usable product interfaces.
homepage: https://design.seedclub.com
registry: https://design.seedclub.com/r/registry.json
install:
  init: "pnpm dlx shadcn@latest init"
  registry: "pnpm dlx shadcn@latest registry add @scui=https://design.seedclub.com/r/{name}.json"
  component: "pnpm dlx shadcn@latest add @scui/button"
  theme: "pnpm dlx shadcn@latest add @scui/theme"
colors:
  light:
    background: "oklch(1 0 0)"
    foreground: "oklch(0.145 0 0)"
    card: "oklch(1 0 0)"
    card-foreground: "oklch(0.145 0 0)"
    popover: "oklch(1 0 0)"
    popover-foreground: "oklch(0.145 0 0)"
    primary: "oklch(0.205 0 0)"
    primary-foreground: "oklch(0.985 0 0)"
    secondary: "oklch(0.97 0 0)"
    secondary-foreground: "oklch(0.205 0 0)"
    muted: "oklch(0.97 0 0)"
    muted-foreground: "oklch(0.556 0 0)"
    accent: "oklch(0.97 0 0)"
    accent-foreground: "oklch(0.205 0 0)"
    destructive: "oklch(0.577 0.245 27.325)"
    border: "oklch(0.922 0 0)"
    input: "oklch(0.922 0 0)"
    ring: "oklch(0.708 0 0)"
    chart-1: "oklch(0.87 0 0)"
    chart-2: "oklch(0.556 0 0)"
    chart-3: "oklch(0.439 0 0)"
    chart-4: "oklch(0.371 0 0)"
    chart-5: "oklch(0.269 0 0)"
    sidebar: "oklch(0.985 0 0)"
    sidebar-foreground: "oklch(0.145 0 0)"
    sidebar-primary: "oklch(0.205 0 0)"
    sidebar-primary-foreground: "oklch(0.985 0 0)"
    sidebar-accent: "oklch(0.97 0 0)"
    sidebar-accent-foreground: "oklch(0.205 0 0)"
    sidebar-border: "oklch(0.922 0 0)"
    sidebar-ring: "oklch(0.708 0 0)"
  dark:
    background: "oklch(0.145 0 0)"
    foreground: "oklch(0.985 0 0)"
    card: "oklch(0.205 0 0)"
    card-foreground: "oklch(0.985 0 0)"
    popover: "oklch(0.205 0 0)"
    popover-foreground: "oklch(0.985 0 0)"
    primary: "oklch(0.922 0 0)"
    primary-foreground: "oklch(0.205 0 0)"
    secondary: "oklch(0.269 0 0)"
    secondary-foreground: "oklch(0.985 0 0)"
    muted: "oklch(0.269 0 0)"
    muted-foreground: "oklch(0.708 0 0)"
    accent: "oklch(0.269 0 0)"
    accent-foreground: "oklch(0.985 0 0)"
    destructive: "oklch(0.704 0.191 22.216)"
    border: "oklch(1 0 0 / 10%)"
    input: "oklch(1 0 0 / 15%)"
    ring: "oklch(0.556 0 0)"
typography:
  fonts:
    sans: "InterVariable, Inter, system UI sans fallback"
    serif: '"Times New Roman", Times, serif'
    distribution: "https://rsms.me/inter/inter.css"
  sans:
    type-sans-xs: { fontSize: "0.75rem", lineHeight: "1.2", letterSpacing: "-0em" }
    type-sans-sm: { fontSize: "0.875rem", lineHeight: "1.2", letterSpacing: "-0em" }
    type-sans-base: { fontSize: "1rem", lineHeight: "1.2rem", letterSpacing: "-0em" }
    type-sans-lg: { fontSize: "1.125rem", lineHeight: "1.2", letterSpacing: "-0em" }
    type-sans-xl: { fontSize: "1.25rem", lineHeight: "1.2", letterSpacing: "-0.01em" }
    type-sans-2xl: { fontSize: "1.5rem", lineHeight: "1.2", letterSpacing: "-0.01em" }
    type-sans-3xl: { fontSize: "1.875rem", lineHeight: "1.1", letterSpacing: "-0.01em" }
    type-sans-4xl: { fontSize: "2.25rem", lineHeight: "1.1", letterSpacing: "-0.02em" }
    type-sans-5xl: { fontSize: "3rem", lineHeight: "1.1", letterSpacing: "-0.03em" }
    type-sans-6xl: { fontSize: "3.75rem", lineHeight: "1.1", letterSpacing: "-0.04em" }
    type-sans-7xl: { fontSize: "4.5rem", lineHeight: "1", letterSpacing: "-0.05em" }
    type-sans-8xl: { fontSize: "6rem", lineHeight: "1", letterSpacing: "-0.05em" }
    type-sans-9xl: { fontSize: "8rem", lineHeight: "1", letterSpacing: "-0.06em" }
  serif:
    type-serif-xs: { fontSize: "0.75rem", lineHeight: "1.2", letterSpacing: "-0.01em" }
    type-serif-sm: { fontSize: "0.875rem", lineHeight: "1.2", letterSpacing: "-0.02em" }
    type-serif-base: { fontSize: "1rem", lineHeight: "1.2", letterSpacing: "-0.02em" }
    type-serif-lg: { fontSize: "1.125rem", lineHeight: "1.2", letterSpacing: "-0.02em" }
    type-serif-xl: { fontSize: "1.25rem", lineHeight: "1.1", letterSpacing: "-0.03em" }
    type-serif-2xl: { fontSize: "1.5rem", lineHeight: "1", letterSpacing: "-0.04em" }
    type-serif-3xl: { fontSize: "1.875rem", lineHeight: "1", letterSpacing: "-0.04em" }
    type-serif-4xl: { fontSize: "2.25rem", lineHeight: "1", letterSpacing: "-0.05em" }
    type-serif-5xl: { fontSize: "3rem", lineHeight: "0.9", letterSpacing: "-0.055em" }
    type-serif-6xl: { fontSize: "3.75rem", lineHeight: "0.9", letterSpacing: "-0.06em" }
    type-serif-7xl: { fontSize: "clamp(3.5rem, 10vw, 5rem)", lineHeight: "0.85", letterSpacing: "-0.065em" }
    type-serif-8xl: { fontSize: "6rem", lineHeight: "0.85", letterSpacing: "-0.07em" }
    type-serif-9xl: { fontSize: "8rem", lineHeight: "0.8", letterSpacing: "-0.075em" }
  usage:
    product: "Use sans typography for product chrome, navigation, controls, forms, tables, and operational UI."
    marketing: "Use serif utilities only for marketing pages and brand-led display moments."
  roles:
    h1: "type-sans-3xl font-semibold"
    h2: "type-sans-2xl font-semibold"
    h3: "type-sans-xl font-medium"
    h4: "type-sans-base font-medium"
    body: "type-sans-sm text-foreground"
    description: "type-sans-sm text-muted-foreground"
    helper: "type-sans-xs text-muted-foreground"
    label: "Label primitive with type-sans-xs or type-sans-sm font-medium"
    eyebrow: "Label primitive with type-sans-xs font-medium text-muted-foreground"
spacing:
  base: 4px
  scale:
    1: 4px
    1.5: 6px
    2: 8px
    2.5: 10px
    3: 12px
    4: 16px
    5: 20px
    6: 24px
    8: 32px
    10: 40px
    12: 48px
    16: 64px
rounded:
  base: "0"
  sm: "calc(var(--radius) * 0.6)"
  md: "calc(var(--radius) * 0.8)"
  lg: "var(--radius)"
  xl: "calc(var(--radius) * 1.4)"
  full: "9999px"
registryGroups:
  layout: [aspect-ratio, card, resizable, scroll-area, separator, sidebar]
  primitives: [avatar, badge, button, button-group, empty, item, kbd, skeleton, spinner]
  forms: [checkbox, combobox, field, input, input-group, input-otp, label, native-select, radio-group, select, slider, switch, textarea]
  overlays: [alert-dialog, context-menu, dialog, drawer, dropdown-menu, hover-card, menubar, popover, sheet, tooltip]
  navigation: [accordion, breadcrumb, collapsible, command, navigation-menu, pagination, tabs, toggle, toggle-group]
  data-feedback: [alert, calendar, carousel, chart, progress, sonner, table]
---

# SCUI

## Overview

SCUI is Seed Club's shadcn registry for building product interfaces: internal tools, dashboards, admin surfaces, and application workflows. It should feel quiet, dense, precise, and easy to scan.

Build the usable surface first. Prefer neutral color, compact controls, clear hierarchy, and direct language. Avoid marketing-page composition, decorative gradients, oversized heroes, and ornamental containers unless the product itself requires them.

## Colors

Each color token encodes interface intent, not decoration. The palette is neutral first, with semantic tokens for surfaces, text, borders, focus, actions, and destructive states:

- `background` is the page surface.
- `card` and `popover` are raised or layered surfaces.
- `muted` is for quiet surface separation, empty states, and secondary regions.
- `border` and `input` define structure without adding visual weight.
- `foreground` is primary text and icons; `muted-foreground` is secondary text, helper copy, and low-emphasis metadata.
- `primary` is the main action color and should usually appear once per local decision area.
- `destructive` is only for destructive actions, errors, and failed states.
- `ring` is the focus-visible color and should stay visible on every interactive element.
- `chart-*` tokens are for data visualization only.
- `sidebar-*` tokens scope navigation surfaces without changing the main page palette.

Use the semantic token names everywhere instead of raw color values. Do not use color as decoration.

The light theme is the default registry theme. The dark theme uses the same token names and is scoped under `.dark`.

## Typography

SCUI distributes Inter from `https://rsms.me/inter/inter.css`. When variable fonts are supported, `InterVariable` becomes the sans stack. Product interfaces use sans typography for every interface role.

Use `type-sans-xs` through `type-sans-9xl` instead of hand-setting size, line height, and letter spacing. Most interface text should stay in the `xs` through `lg` range. Use larger sizes for page titles, display type, and empty states only when the surface has room for them.

Use `type-serif-xs` through `type-serif-9xl` only for marketing pages and brand-led display moments. Serif type should never appear in product chrome: navigation, controls, forms, tables, repeated panels, command surfaces, or other operational UI stay sans.

Use type roles consistently:

- H1: `type-sans-3xl font-semibold` for page titles.
- H2: `type-sans-2xl font-semibold` for major sections.
- H3: `type-sans-xl font-medium` for subsection headings.
- H4: `type-sans-base font-medium` for compact panel and group titles.
- Body: `type-sans-sm text-foreground` for normal interface copy.
- Description and helper text: `type-sans-sm` or `type-sans-xs` with `text-muted-foreground`.

Use the `Label` primitive for form labels, compact section titles, and occasional eyebrow text. Labels should usually be Capitalized or sentence case. Uppercase is allowed when it is a deliberate metadata or chrome treatment, but it should not become the default style for fields, cards, navigation, or every section title.

## Layout

Layout follows a 4px rhythm:

- 4-8px for tight relationships inside controls.
- 12-16px for grouped fields, toolbar gaps, and compact panels.
- 24-32px for section spacing.
- 40-64px for major page transitions.

Pages should be full-width app surfaces with constrained inner content where needed. Use cards for repeated content items, modals, and framed tools. Never nest cards inside cards; use spacing, borders, or section headers to organize content inside a card.

Assign scrolling only to regions with real overflow, such as feeds, lists, tables, panels, or refreshable content areas. Keep the body fixed with `overscroll-behavior` so the app shell does not move when there is no page-level content to scroll.

## Shapes

The base registry radius is `0`, so buttons, inputs, cards, and default surfaces render square. Components still use semantic radius classes such as `rounded-lg` and `rounded-xl` in code, but those classes resolve to `0` because they are derived from `--radius`.

Keep shapes consistent inside a view. Do not mix sharp corners, pills, and heavily rounded cards unless the component type requires it. Pills are reserved for avatars, badges, and intentionally pill-shaped controls.

## Registry Primitives

Always use SCUI registry primitives before creating local UI. The registry is the source of truth for component size, spacing, states, accessibility behavior, and visual details.

When implementing UI from this guide, translate design intent into the canonical design-system layer: shared tokens, theme variables, CSS utilities, and component APIs.

Treat adapters as stable integration boundaries. Adapters may translate data, state, or framework conventions, but they should not redefine visual appearance, spacing, state styling, or component structure.

Consume adapters as published system interfaces. When the current design system needs a new primitive or visual capability, propose a first-class token, theme variable, CSS utility, or component API update instead of creating a local visual workaround.

Install primitives through the `@scui` registry namespace.

Build product UI by composing registry primitives:

- Actions and modes: `button`, `button-group`, `toggle`, `toggle-group`, `tabs`.
- Forms: `field`, `label`, `input`, `textarea`, `select`, `checkbox`, `radio-group`, `switch`, `slider`.
- Overlays: `dialog`, `alert-dialog`, `sheet`, `drawer`, `popover`, `dropdown-menu`, `context-menu`, `menubar`, `hover-card`, `tooltip`.
- Navigation: `sidebar`, `navigation-menu`, `breadcrumb`, `pagination`, `accordion`, `collapsible`, `command`.
- Data and feedback: `card`, `table`, `alert`, `empty`, `skeleton`, `spinner`, `progress`, `sonner`, `chart`, `carousel`.

Do not hand-roll a primitive that exists in the registry. If a primitive is close but insufficient, extend it or improve the registry instead of bypassing it.

Form labels stay neutral; validation belongs on the control and error copy. Error text should be `text-xs`. Clarifying text should sit before the field when it explains what to enter.

Menus, popovers, dialogs, and sheets should stay compact. Use clear item labels and avoid unnecessary group names. On mobile, collapse sidebar navigation into a right-side sheet.

## Motion

Motion should clarify state changes. Keep transitions short and make controls feel immediate. Avoid decorative loops.

## Voice & Content

Copy should be direct and specific:

- Use concise Title Case for short UI labels such as page titles, navigation items, tabs, and primary actions.
- Use sentence case for descriptions, helper text, error copy, empty states, toasts, and any copy that reads like a sentence.
- Name actions with a verb and noun where possible, such as `Install Component` or `Copy Command`.
- Errors should say what happened and what to do next.
- Empty states should point to the first useful action.
- Avoid filler, marketing phrasing, and explaining the UI inside the UI.

## Do's and Don'ts

- Use the registry theme before overriding local tokens.
- Use the type utilities for intentional typography.
- Use SCUI registry primitives before creating local UI.
- Use lucide icons for actions when an icon exists.
- Keep controls compact and stable in size.
- Keep page sections unframed unless the content is a repeated item, modal, or tool.
- Do not use adapters to override registry appearance; update the design-system layer instead.
- Do not use uppercase as the default label treatment.
- Do not add decorative gradient orbs, bokeh blobs, or generic hero art.
- Do not use color alone to communicate status.
- Do not remove keyboard focus states; replace prominent rings with quieter visible treatments.