design philosophy

backgrounds

borders

text

accent (copper)

status

status (light backgrounds)

color usage rules

contrast ratios (wcag aa)

font families

type scale

line height

max line width

usage rules

heading hierarchy

spacing scale

semantic spacing

motion principles

duration tokens

easing tokens

interactive demo

standards

focus management

color independence

screen reader support

breakpoints

density modes

Density modes adjust spacing, font size, and row heights for different contexts. Essential for data-dense developer tools.

grid system

voice & tone

microcopy rules

empty states

loading states

data color palette

quality score visualization

Tool quality scores use a consistent visual language across the platform.

progress indicators

animated counters

icon sizes

usage rules

semantic icons

all icons

token architecture

/* Core tokens (don't override) */
--copper-500: 22 57% 41%;

/* Semantic tokens (safe to override) */
--primary: var(--copper-500);
--primary-hover: 22 57% 35%;
--accent: var(--primary);

/* Component tokens (for advanced customization) */
--button-bg: hsl(var(--primary));
--button-hover-bg: hsl(var(--primary-hover));

dark mode

Dark mode is opt-in via the .dark class on the root element. All semantic tokens have dark mode variants.

embedding guidance

button

badge

card

accordion

breadcrumbs

form elements

slider

progress bar

tabs

table

pagination

dropdown menu

popover

tooltip

modal

drawer

spinner

skeleton

state components

page header

stat card

quality score

install snippet

toast

code block

import { Button } from '@tpmjs/ui/Button/Button';

export function MyComponent() {
  return (
    <Button variant="default">
      click me
    </Button>
  );
}

button api

// Basic usage
<Button>click me</Button>

// With variant and size
<Button variant="destructive" size="lg">
  delete tool
</Button>

// Loading state
<Button loading>publishing...</Button>

// With icon
<Button>
  <Icon icon="plus" size="sm" className="mr-2" />
  add tool
</Button>

input api

// Basic usage
<Input placeholder="enter text..." />

// With error state
<Input
  state="error"
  placeholder="invalid input"
/>

// With FormField wrapper
<FormField
  label="Email"
  error="Invalid email address"
>
  <Input state="error" />
</FormField>

anti-patterns

// ❌ Using inline styles
<Button style={{ backgroundColor: 'red' }}>
  delete
</Button>

// ❌ Nesting buttons
<Button>
  <Button>nested</Button>
</Button>

// ❌ Missing accessible name
<Button size="icon">
  <Icon icon="plus" />
</Button>

// ✅ Using variants
<Button variant="destructive">
  delete
</Button>

// ✅ Single button
<Button>action</Button>

// ✅ With aria-label
<Button size="icon" aria-label="Add item">
  <Icon icon="plus" />
</Button>

global navigation (header)

The primary header navigation appears on every page and provides access to main sections.

sidebar navigation

Vertical sidebar for section-level navigation within the app.

breadcrumbs

Show hierarchical location and enable navigation back to parent pages.

tab navigation

For switching between views within a page context.

mobile navigation

Hamburger menu pattern for narrow viewports.

validation timing

Choose validation timing based on the field type and user expectations.

error summary

For forms with multiple errors, show a summary at the top.

help text placement

required vs optional

field grouping

Group related fields with visual hierarchy.

danger zone

Destructive actions require explicit confirmation.

feedback decision tree

toast notifications

Ephemeral messages that appear briefly and auto-dismiss.

inline alerts

Persistent messages within content flow.

global banners

System-wide announcements that span the full width.

progress indicators

For long-running operations, show determinate progress when possible.

retry patterns

When operations fail, provide clear retry options.

sortable columns

Click column headers to sort. Show sort direction with icons.

row selection + bulk actions

Select rows to enable bulk actions. Show action bar when rows are selected.

pagination

Use pagination for large datasets. Show page info and navigation.

empty & loading states

density integration

Tables respect the page density mode for compact views.

search box states

Search boxes should show clear states and provide helpful feedback.

filter chips

Use chips to show active filters with easy removal.

filter panel

For complex filtering, use a dedicated panel with grouped options.

saved views

Allow users to save and recall filter combinations.

query syntax display

For power users, display the underlying query syntax.

command palette

Quick access to search and navigation via keyboard shortcut.

aria patterns & keyboard

Each component has specific ARIA patterns and keyboard interactions that must be implemented.

focus management

Proper focus management is critical for keyboard and screen reader users.

// Focus trap implementation
const dialogRef = useRef<HTMLDivElement>(null);
const triggerRef = useRef<HTMLButtonElement>(null);

// Save trigger reference before opening
const handleOpen = () => {
  triggerRef.current = document.activeElement as HTMLButtonElement;
  setOpen(true);
};

// Restore focus on close
const handleClose = () => {
  setOpen(false);
  triggerRef.current?.focus();
};

screen reader announcements

Use live regions to announce dynamic content changes.

color contrast requirements

All text must meet WCAG AA contrast requirements (4.5:1 for normal text, 3:1 for large text).

reduced motion support

Respect the prefers-reduced-motion media query for users who experience motion sickness or vestibular disorders.

// CSS approach
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

// React hook approach
import { useReducedMotion } from '@tpmjs/ui/system/hooks/useReducedMotion';

function AnimatedComponent() {
  const prefersReducedMotion = useReducedMotion();

  return (
    <div
      className={prefersReducedMotion ? 'instant' : 'animated'}
    />
  );
}

testing checklist

Before shipping any component, verify accessibility with these tests.

glossary

Use these terms consistently throughout the platform.

verb consistency

Use these verbs for common actions to maintain consistency.

capitalization

Follow these capitalization rules for UI text.

numbers & formatting

Format numbers and data consistently.

error messages

Write error messages that are helpful and actionable.

icon library

Source: Lucide React. Icons should be imported from @tpmjs/ui/Icon/Icon.

icon sizes

Choose icon size based on context and surrounding content.

icon usage guidelines

When and how to use specific icons.

icon styling

Consistent styling rules for icons in different contexts.

adding new icons

Process for adding new icons to the system.

// icons.ts
import { Heart } from 'lucide-react';

export const icons = {
  // ...existing icons
  heart: Heart,
};

export type IconName = keyof typeof icons;