# ClipMate design

Canonical URL: https://clipmate.dev/design.md

Use this guide to build or change ClipMate's website, desktop workspace, browser extension, and product imagery. It documents ClipMate's existing visual language and interaction patterns. Use the [brand guide](https://clipmate.dev/brand.md) for identity and the [voice guide](https://clipmate.dev/voice.md) for copy.

## Design character

ClipMate is a compact, practical, monospace-first tool. White and zinc/slate surfaces, burnt-orange actions, crisp borders, small corner radii, and hard offset shadows give controls a tactile quality. Typography and spacing carry ordinary content; shadows distinguish interaction.

When decisions compete, preserve the task, the content's meaning, and accessible operation first. Then preserve the shared tokens and the target surface's established components. Add visual emphasis only where it helps someone understand or act.

This is the maintained design guide. Shared CSS tokens are the implementation authority for exact values; update this document when an intentional implementation change alters the system. Design-tool captures and generated screen descriptions are references, not additional design authorities.

## Integrate with the existing surface

Use the existing shared typography, colors, spacing, CSS recipes, and SVG primitives consistently across each surface. Reuse established components for behavior and composition. Avoid creating another palette, button system, or theme layer for a new page. Provider-branded sign-in controls and native operating-system window controls retain their explicit platform conventions.

## Product mark and media

Use the existing clipboard mark and ClipMate wordmark treatment. Icons come from the shared SVG set, normally on a 24×24 grid with a 2px stroke and `currentColor`; compact controls can use their existing smaller sizes. Keep visual style consistent within a surface, with provider and platform marks as deliberate exceptions.

Use real product captures or accurate interface examples. Preserve aspect ratio, readable labels, and actual product states. App-window screenshots and videos remain rectangular without added corner rounding. Avoid invented dashboards, testimonials, metrics, and decorative media that obscures the workflow.

## Color and themes

Choose semantic variables for the role being styled. The light palette is white and zinc; dark mode uses the existing OKLCH slate values. Status colors communicate status rather than becoming additional brand accents.

| Role / token | Light | Dark |
| --- | --- | --- |
| Canvas `--bg-primary` | `#ffffff` | `oklch(0.21 0.006 285.8)` |
| Inset `--bg-secondary` | `#f4f4f5` | `oklch(0.14 0.005 285.8)` |
| Chrome / hover `--bg-chrome`, `--bg-hover` | `#e4e4e7` | `oklch(0.27 0.006 285.8)` |
| Primary text `--text-primary` | `#18181b` | `oklch(0.98 0.002 247.8)` |
| Secondary text `--text-secondary` | `#52525b` | `oklch(0.75 0.01 285.8)` |
| Tertiary text `--text-tertiary` | `#a1a1aa` | `oklch(0.70 0.01 285.8)` |
| Subtle border `--border-subtle` | `#e4e4e7` | `oklch(0.27 0.006 285.8)` |
| Action `--accent-primary` | `#c04a00` | `oklch(0.55 0.17 50.4)` |
| Current source `--bg-current` | `#fef3c7` | `rgba(245, 158, 11, 0.15)` |

`--accent-text` is the action color in light mode and a lighter orange mix in dark mode. Use it for readable accent text. `--focus-ring-color` follows `--accent-primary` in both themes. `--bg-emphasis` is a subtle orange tint for selective callouts, distinct from the amber current-source fill.

Error, success, information, and warning accents use `--accent-error`, `--accent-success`, `--accent-info`, and `--accent-warning`. Their light references are red `#ef4444`, emerald `#10b981`, blue `#3b82f6`, and amber `#f59e0b`. Error, success, and warning messages also have matching `--bg-*`, `--text-*`, and `--border-*` status tokens; use these combinations rather than arbitrary saturated text on a tinted background.

Themes follow system preference unless an explicit `data-theme` choice overrides it. The shared theme rules also set native `color-scheme` so browser controls and scrollbars follow that choice. Preserve semantic mappings rather than mechanically inverting colors. Use orange for actions and focus across the website and app. Verify contrast on the actual background, including secondary text, status colors, and focused controls. Empty-source guidance and placeholders use `--text-secondary` at full opacity; error messages use `--text-error` rather than the brighter error accent.

## Typography

The shared application family is:

```css
--font-family: ui-monospace, Menlo, Monaco, Consolas, "SFMono-Regular", monospace;
```

The website also configures JetBrains Mono through `--font-mono`, used by the logo and elements that request that variable. Its body uses the shared `--font-family`. Keep this scope explicit: JetBrains Mono is not a global desktop requirement.

| Token | Shared size | Typical role |
| --- | --- | --- |
| `--font-xs` | 10px | Small captions and tags; keep essential instructions larger |
| `--font-sm` | 14px | Toolbar, labels, metadata |
| `--font-base` | 16px | Body and interactive entry titles |
| `--font-lg`, `--font-xl` | 18px, 20px | App section and view headings |
| `--font-2xl`, `--font-3xl`, `--font-4xl` | 24px, 30px, 36px | Page headings |
| `--font-5xl`, `--font-6xl` | 48px, 60px | Large marketing headings |

Weights are 400, 500, 600, and 700. Leading tokens are 1.2, 1.5, and 1.625. App body text uses 1.5; web body uses relaxed leading, with paragraph leading around 1.6. Headings are bold and compact. Use restrained uppercase only for established small labels.

Web sizes are fluid overrides, not fixed desktop app sizes. For example, body type is `clamp(1rem, 0.95rem + 0.25vw, 1.125rem)` and the largest heading token is `clamp(3.75rem, 3rem + 3.75vw, 6rem)`. Reuse those variables rather than freezing display sizes on a narrow screen. Keep prose at a comfortable reading measure, approximately 65 characters where the layout permits.

## Space, shape, and depth

| Token family | Values |
| --- | --- |
| Spacing `--space-2xs` through `--space-4xl` | 4, 6, 12, 18, 24, 36, 48, 64, 96px |
| Border `--border-width`, `--border-width-thin` | 2px, 1px |
| Radius small / default / large / extra large / pill | 4px, 6px, 8px, 12px, 999px |
| Shadow offset small / medium / large | 2px, 4px, 6px |

Hard shadows have zero blur. Interactive entries use the small offset; buttons use the medium offset. Large lifted controls use the large offset only where their existing interaction warrants it. A press translates down-right by `--press-offset` (2px) and collapses the shadow. Ordinary content stays flat. Use the shared shadow variables so theme ink remains correct.

## Surfaces and composition

Start with plain content. A card earns its border, radius, and hard shadow when the container itself is clickable or selectable. A button inside a section does not make the entire section an interactive card.

| Class | Treatment | Use |
| --- | --- | --- |
| `.surface-plain` | No chrome | Narrative, open lists, headings |
| `.surface-ruled` | Hairline separators | Section structure |
| `.surface-inset` | Muted fill, no shadow | Quiet grouping |
| `.surface-emphasis` | Subtle accent tint, no shadow | A preferred option or important callout |
| `.surface-table` | Structural frame, no shadow | Comparison and data tables |
| `.surface-interactive` | Border, small radius, hard shadow | Linked tiles and selectable entries |

Existing `.surface-card` and `.card` aliases resolve to the interactive recipe; choose `.surface-interactive` for new containers. Hero content stays open. Use aligned typography, ruled sections, or a selective tint instead of repeating equal decorative boxes around prose.

Marketing uses a contained shell up to 1280px. The homepage is text-led, with one reading column for Smart Paste. Keep descriptions around 65 characters per line. The shared web container has 96px desktop padding, changing below 768px to 48px vertically and 18px horizontally. New layouts should preserve clear reading order and spatial zones rather than overlapping text and imagery.

The shared desktop/extension workspace is denser: compact titlebar navigation, internal scrolling, and content width `clamp(370px, 90%, 860px)`. Notes and prompt entries use 12px gaps and 18px padding because the entries are interactive. The current-source dock aligns with the content column. Preserve host-specific window and browser sizing instead of applying the marketing shell to the app.

## Components and states

- **Buttons:** use shared `.btn` variants and size helpers, or the target app's existing wrapper. Primary, secondary, danger, and text variants have distinct roles. Labels name the action. Use links for navigation and buttons for actions. Resting hard shadows collapse on press; disabled state must be evident and non-interactive.
- **Inputs:** visible labels above fields, optional help and errors below. Standard inputs/selects are approximately 40px high with 6px vertical and 12px horizontal padding, a muted fill, 2px border, 6px radius, and no hard shadow. Textareas use 12px padding. Placeholder text supplements a label. Checkboxes are approximately 18px square.
- **Navigation:** preserve compact, text-led website navigation and the app's Smart Paste/Quick Notes tabs. Keep the feature tabs and window controls on one row at desktop sizes. At 520px or narrower, place the tabs on a second row so their full names stay clear of Help and Settings. Native macOS window controls retain native behavior and appearance.
- **Dialogs:** solid surfaces, structural borders, concise titles, a dim backdrop, and clear actions. Reuse the existing dialog's focus management and accessible title/description. Fit the available viewport and keep scrolling content and actions reachable.
- **Tables:** retain semantic headers and aligned columns. Use a frame without hard shadow. Highlight a meaningful preferred column with emphasis rather than boxing every cell.
- **Status:** pair text with semantic color. Show the failed action and available next step near the relevant control. Announce important asynchronous results through the existing live-status/alert pattern.
- **Loading and empty states:** match the real layout and activity. Existing spinners or loading pulses are appropriate for actual waits. An empty state explains the next useful action without inventing saved content or product data.

## Interaction and motion

Use the shared button and surface interaction recipes for hover, active, focus, and disabled states. Hover effects apply only with `(hover: hover) and (pointer: fine)`; keyboard focus remains available independently of pointer capabilities. Buttons change fill or brightness on hover. Interactive tiles may lift slightly; static sections remain still.

The token durations are 100ms for fast feedback, 150ms for modals, 200ms for ordinary transitions, and 300ms for slower exceptional transitions. The shared exit curve is `cubic-bezier(0.23, 1, 0.32, 1)`. App entries use short 100ms feedback; dialogs use brief opacity/transform transitions. Press feedback uses translation rather than scale.

Name transition properties explicitly. Use transform and opacity for moving content rather than animating layout dimensions. Keep frequent navigation and selection immediate. Activity loops communicate actual processing; perpetual decoration, forced staggered lists, and spring physics are not requirements of the implemented system.

Honor `prefers-reduced-motion`: remove nonessential movement, pulses/spinners, dialog/list motion, and smooth scrolling as the existing surface does. Keep state changes understandable without animation. Preserve functional platform effects, such as an explicit transparency preference or a scroll-edge fade, within their existing scope.

## Responsive behavior and accessibility

The website reflows around 768px; the app and extension also have host-specific breakpoints and container queries. Reflow columns and controls before shrinking text. Let grid/flex children shrink with `min-width: 0`, wrap long content, and keep local table/list scrolling usable. Do not rely on a page overflow clip to hide layout defects. Keep product media legible and long translated labels operable.

The website's compact header controls preserve 44×44px targets. Maintain that touch affordance when changing web navigation. Dense desktop controls follow their existing host conventions; ensure they remain reachable by keyboard and have accessible names.

Keyboard focus uses the same gapped orange outline across themes:

```css
:focus-visible {
  outline: var(--focus-ring-size) solid var(--focus-ring-color);
  outline-offset: var(--focus-offset);
}
```

Both thickness and gap are 2px. Controls with hard shadows remove those shadows on focus so the gap remains clear. Do not clip the outline or replace it with color alone.

The shared app toolbar, Add actions, search, Help, and composer remain reachable in the normal Tab sequence. Search draws the focus outline around its complete control. Reordering must also offer named Move up / Move down actions and keyboard operation; dragging cannot be the only way to arrange saved content. Confirm single-item deletion and dirty-editor dismissal before discarding deliberate notes, saved prompts, or unsaved edits.

Preserve the website's skip link, page language, main landmark, logical headings, native controls, and meaningful media alternatives. Keep form labels associated with fields; give icon-only actions accessible names. Use text and structure alongside status color. Verify contrast, keyboard operation, zoom/reflow, and reduced motion in both themes. These are acceptance requirements, not a claim that the entire product has completed a WCAG certification.

## Review a change

Inspect the actual target surface at narrow and wide widths, in light and dark mode, with keyboard focus and reduced motion. Check normal, hover, pressed, disabled, loading, empty, and error states relevant to the change. Confirm that content still reads clearly, actions match their labels, media depicts the real product, and every public link resolves.

For design generation, name the target surface and supply the relevant sections from this guide together with current product copy. Check proposals against the established components, shared CSS tokens, and this guide.

## Public references

- [ClipMate](https://clipmate.dev/)
- [Brand and terminology](https://clipmate.dev/brand.md)
- [Voice and tone](https://clipmate.dev/voice.md)
- [Smart Paste](https://clipmate.dev/smart-paste-ai/)
- [Privacy Policy](https://clipmate.dev/privacy/)
