# Supportsheep design system

This is the canonical design context for fixed Supportsheep surfaces. Read `.agents/brand.md` before changing product identity.

## Overview

Supportsheep uses a calm dusk system for interviews, content work, and support tools. Violet accents and the sheep mark keep the product recognizable.

The shared tokens live in `apps/web/src/app/globals.css`. Shared primitives live in `packages/ui/src/primitives/`.

Keep product styling separate from tenant public themes. Tenant values enter through `config.publicAppearance`, not global tokens.

Design for these surface types:

- Apex marketing and documentation.
- Account, editor, settings, and support tools.
- Focused guest interview flows.
- Tenant-owned public knowledge bases and articles.

## Colors

Use semantic OKLCH tokens. Define light and dark behavior together.

| Role | Light value | Dark value | Use |
| --- | --- | --- | --- |
| `--background` | `oklch(0.99 0.004 285)` | `oklch(0.16 0.025 285)` | Page canvas |
| `--foreground` | `oklch(0.17 0.02 285)` | `oklch(0.96 0.006 285)` | Text and strong borders |
| `--card` | `oklch(1 0.003 285)` | `oklch(0.21 0.03 285)` | Persistent panels |
| `--primary` | `oklch(0.55 0.23 285)` | `oklch(0.68 0.2 285)` | Main actions and brand accents |
| `--secondary` | `oklch(0.96 0.02 285)` | `oklch(0.28 0.04 285)` | Supporting actions |
| `--muted` | `oklch(0.965 0.008 285)` | `oklch(0.27 0.025 285)` | Quiet surfaces |
| `--accent` | `oklch(0.96 0.04 75)` | `oklch(0.32 0.05 75)` | Warm dusk emphasis |
| `--border` | `oklch(0.92 0.01 285)` | `oklch(0.98 0.02 285 / 14%)` | Dividers and boundaries |
| `--ring` | `oklch(0.55 0.23 285)` | `oklch(0.68 0.2 285)` | Keyboard focus |
| `--link` | `oklch(0.55 0.23 285)` | `oklch(0.74 0.18 285)` | Text links |

The asset pack uses `#6D4AFF`. Product code uses `--primary` instead of that hex value.

Use `--success-*`, `--warning-*`, `--error-*`, and `--info-*` only for their named status.

Apply tenant colors through the public-theme layer. Never change global product variables for one tenant.

## Typography

Geist Sans is the default product face. Geist Mono handles code, machine values, and compact technical labels.

IBM Plex Sans supports apex marketing surfaces. Tenant article fonts remain tenant-controlled.

- Use `font-sans` for navigation, forms, settings, and body copy.
- Use `font-mono` for commands, IDs, counts, and structured values.
- Use tabular numbers where changing digits could move the layout.
- Keep headings short and preserve heading order.
- Use `text-wrap: balance` for headings and `text-wrap: pretty` for prose.
- Do not use tenant-loaded fonts as product defaults.

## Layout

Apex marketing sections use a centered `max-w-6xl` container with `px-4 sm:px-6` gutters.

- Start with one column and add grids at named breakpoints.
- Keep the main action beside its message.
- Keep guest interview pages focused and free of unrelated navigation.
- Follow existing sidebar and content-shell patterns in product tools.
- Constrain long article content and handle overflow deliberately.
- Preserve readable gutters and touch targets on narrow screens.

Tenant public pages may change layout through the supported theme settings. Product shells remain fixed.

## Elevation & Depth

Use the three named shadow tokens.

| Token | Value | Use |
| --- | --- | --- |
| `--shadow-subtle` | `rgba(0, 0, 0, 0.04) 0 1px 2px` | Small controls and quiet cards |
| `--shadow-keystone` | Two compact low-opacity layers | Interactive cards and lifted states |
| `--shadow-floating` | Outline plus `0 8px 24px -4px` | Menus, popovers, and dialogs |

Use surface color and border hierarchy before adding a shadow. Reserve floating depth for transient content.

## Shapes

The base radius is `--radius: 0.625rem`. Tailwind radius roles derive from it.

| Role | Formula |
| --- | --- |
| `sm` | `calc(var(--radius) - 4px)` |
| `md` | `calc(var(--radius) - 2px)` |
| `lg` | `var(--radius)` |
| `xl` | `calc(var(--radius) + 4px)` |
| `2xl` | `calc(var(--radius) + 8px)` |
| `3xl` | `calc(var(--radius) + 12px)` |
| `4xl` | `calc(var(--radius) + 16px)` |

Use the base radius for controls and cards. Use pills for badges, status, and short selectors.

Reuse the existing `SheepMark`. Do not approximate its silhouette with another drawing.

## Components

Prefer `packages/ui` primitives before building a local variant.

### Buttons and links

- Use `default` for the primary action.
- Use `secondary` or `outline` for supporting actions.
- Use `ghost` for low-emphasis navigation.
- Preserve disabled, hover, active, and focus-visible states.

### Cards and floating panels

Use `--card` for persistent panels and `--popover` for transient content. Do not give routine dashboard panels floating depth.

### Forms and feedback

- Give every field a visible label or accessible name.
- Use `--input` for boundaries and `--ring` for keyboard focus.
- Put validation beside the affected control.
- Pair status color with text or an icon.
- Never rely on color alone.

### Brand and motion

Use `SheepMark` for inline brand imagery. Use approved files from `branding/` for composed marketing assets.

Tie motion to meaning or direct feedback. Honor `prefers-reduced-motion` without hiding content or actions.

## Do's and Don'ts

### Do

- Read `.agents/brand.md` before changing product identity.
- Use semantic tokens and shared primitives.
- Define light, dark, keyboard, and reduced-motion behavior together.
- Keep product and tenant values separate.
- Test contrast, focus, narrow layouts, and content overflow.
- Reuse the canonical sheep mark and supplied assets.

### Don't

- Do not hardcode `#6D4AFF` in product components.
- Do not redraw, stretch, crop, or decorate the sheep mark.
- Do not apply product tokens over a tenant theme.
- Do not remove focus rings.
- Do not use floating shadows for routine flat content.
- Do not ship motion without an equivalent reduced-motion state.