Amigo Design System

An accessible UI foundation and application scaffolding layer for Amigo products. Built on Radix UI, Tailwind CSS, and shadcn/ui patterns.

Packages

This design system publishes layer-specific npm packages. amigo-ai/design-hq is the language source of truth; amigo-ai/design-system is the implementation source of truth for consumer apps.

| Package | Purpose | Version | | ------------------------- | --------------------------------------------------------- | -------- | | @amigo-ai/tokens | Colors, typography, spacing, globals.css, Tailwind preset | 4.12.0 | | @amigo-ai/ui-utils | cn() and shared class/variant utilities | 4.3.0 | | @amigo-ai/primitives | Radix-wrapped primitives and building blocks | 8.16.0 | | @amigo-ai/patterns | Layout patterns, page shells, AmigoTable | 34.4.0 | | @amigo-ai/design-review | Design HQ reviewer metadata, scan API, CLI | 0.2.0 | | @amigo-ai/ui | Compatibility umbrella package | 1.3.0 |

Production apps should import from the owning layer package instead of the compatibility umbrella.

Install

pnpm add @amigo-ai/tokens @amigo-ai/ui-utils @amigo-ai/primitives @amigo-ai/patterns
pnpm add -D @amigo-ai/design-review

// tailwind.config.ts
import { amigoPreset } from "@amigo-ai/tokens/tailwind-preset";

export default {
  presets: [amigoPreset],
  content: [
    "./src/**/*.tsx",
    "./node_modules/@amigo-ai/primitives/**/*.{js,tsx}",
    "./node_modules/@amigo-ai/patterns/**/*.{js,tsx}",
  ],
};

// app/layout.tsx - loads brand fonts, CSS variables, and type classes
import "@amigo-ai/tokens/globals.css";

Consumers must also have compatible peer dependencies installed in the app:

• react
• react-dom
• tailwindcss

Some components also rely on optional peers that should be installed only if used:

• react-hook-form
• recharts
• @tanstack/react-table
• @tanstack/react-virtual

AI Agent Consumption Guide

Use this section as the implementation contract when an AI agent is asked to build a new app with the Amigo design-system packages.

Design HQ source of truth

Design language decisions come from amigo-ai/design-hq. These packages encode that source through tokens, utilities, primitives, patterns, and the amigo-design-review CLI. Consumer apps should depend on the layer-specific packages: @amigo-ai/tokens, @amigo-ai/ui-utils, @amigo-ai/primitives, @amigo-ai/patterns, and @amigo-ai/design-review.

Every split package also exports ./design-hq metadata so coding agents and CI can inspect the source commit, package ownership, and consumer rules without scraping prose:

import { designHqAgentWorkflow, designHqPackageContracts } from "@amigo-ai/primitives/design-hq";

The current embedded Design HQ reference is:

• Repository: https://github.com/amigo-ai/design-hq.git
• Commit: b5efe278188dd888d6c1eedb660d66d22825c59c
• Synced: 2026-04-26

Run design alignment reviewers in a consumer repo:

pnpm exec amigo-design-review --severity error src tailwind.config.ts components.json
pnpm exec amigo-design-review --max-findings 200 src
pnpm exec amigo-design-review --severity error --format github src tailwind.config.ts

The first command is CI-friendly and enforces hard source-of-truth errors. The second command runs the broader warning reviewers for colors, borders, shadows, chart literals, focus states, icon-button labels, motion, typography, spacing, and brand-surface drift.

For repeatable CI and agent runs, add amigo-design-review.config.json at the consumer repo root:

{
  "targets": ["src", "tailwind.config.ts", "components.json"],
  "severity": "error",
  "maxFindings": 200
}

The CLI automatically reads amigo-design-review.config.json or .amigo-design-review.json. Use --format github or --github-annotations in GitHub Actions to emit inline code-review annotations, and --summary-file "$GITHUB_STEP_SUMMARY" to write a job summary.

Required setup

1. Install the packages and required peers:

pnpm add @amigo-ai/tokens @amigo-ai/ui-utils @amigo-ai/primitives @amigo-ai/patterns react react-dom tailwindcss
pnpm add -D @amigo-ai/design-review

2. Load the design system stylesheet once at the app root:

import "@amigo-ai/tokens/globals.css";

3. Extend Tailwind with the shared preset:

import { amigoPreset } from "@amigo-ai/tokens/tailwind-preset";

export default {
  presets: [amigoPreset],
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./app/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@amigo-ai/primitives/**/*.{js,tsx}",
    "./node_modules/@amigo-ai/patterns/**/*.{js,tsx}",
  ],
};

4. Build pages from exported primitives and patterns instead of reimplementing core UI.

Agent rules

• Prefer imports from the owning @amigo-ai/* design package before creating local replacements.
• Use ResourcePage, PageContainer, PageSection, InfoCard, StatCard, and TablePage for app layout.
• Use Button, Badge, Input, Select, Textarea, Dialog, Sheet, Tabs, and Form for interaction patterns.
• Keep styling in Tailwind utility classes and design system tokens; do not add CSS modules or styled-components.
• Preserve the flat visual language: borders for structure, no decorative shadows.
• Use semantic spacing and typography tokens already exposed by the preset and globals.css.
• Only install optional peers when the chosen components need them.

Default stack assumptions

An AI agent can safely assume the following app setup unless told otherwise:

• React app using TypeScript
• Tailwind CSS configured in the host app
• App root can import a global CSS file
• Routing can be Next.js App Router, React Router, or another React router
• Local app code owns data fetching, auth, mutations, and state management

What the package provides

• Shared UI building blocks: buttons, inputs, dialogs, tables, badges, tabs, cards, and overlays
• Higher-level product scaffolding: page shells, resource pages, filter bars, settings layouts, and detail layouts
• Design tokens: colors, typography, spacing, borders, and brand fonts
• Tailwind preset and global CSS for consistent visual language

What the package does not provide

• Data fetching or API clients
• Authentication or authorization logic
• Analytics, telemetry, or feature flags
• App-specific business logic
• Routing, form schemas, or server actions

Recommended app scaffold

import {
  FilterBar,
  FilterSearch,
  InfoCard,
  InfoRow,
  PageSection,
  ResourcePage,
  StatCard,
} from "@amigo-ai/patterns";
import { Badge, Button } from "@amigo-ai/primitives";

export function CustomersPage() {
  return (
    <ResourcePage
      title="Customers"
      description="Manage accounts, health, and recent activity."
      actions={<Button>Add customer</Button>}
      filters={
        <FilterBar>
          <FilterSearch placeholder="Search customers" />
          <Badge variant="neutral">All segments</Badge>
        </FilterBar>
      }
    >
      <PageSection title="Overview">
        <div className="grid gap-4 md:grid-cols-3">
          <StatCard label="Active" value="1,284" />
          <StatCard label="At risk" value="43" />
          <StatCard label="Expansion" value="$82k" />
        </div>
      </PageSection>

      <PageSection title="Details">
        <InfoCard title="Selected customer">
          <InfoRow label="Status" value="Healthy" />
          <InfoRow label="Owner" value="Success team" />
        </InfoCard>
      </PageSection>
    </ResourcePage>
  );
}

Optional feature add-ons

Install these only when the app uses the related components:

• react-hook-form for form wrappers and controlled form flows
• recharts for chart components
• @tanstack/react-table for advanced data tables
• @tanstack/react-virtual for virtualized table or list rendering

Agent prompt starter

Build a React + TypeScript page using the Amigo design-system packages. Import @amigo-ai/tokens/globals.css once at the app root, extend Tailwind with @amigo-ai/tokens/tailwind-preset, import primitives from @amigo-ai/primitives, import page patterns from @amigo-ai/patterns, keep all styling in Tailwind classes, and follow the flat Amigo visual language with borders instead of shadows.

Usage

import { Badge, Button, CopyButton } from "@amigo-ai/primitives";
import { InfoCard, InfoRow, ResourcePage, StatCard } from "@amigo-ai/patterns";

<ResourcePage
  title="Dashboard"
  description="Track call volume, quality, and deployment health."
  actions={<Button withArrow>Book a Demo</Button>}
  filters={<Badge variant="neutral">Last 30 days</Badge>}
>
  <div className="grid grid-cols-3 gap-4">
    <StatCard label="Total Calls" value="12,847" />
    <StatCard label="Avg Duration" value="4m 32s" />
    <StatCard label="CSAT" value="94%" />
  </div>

  <InfoCard title="Agent Details">
    <InfoRow label="Status" value={<Badge variant="success">Active</Badge>} />
  </InfoCard>
</ResourcePage>;

Design Language

Core design tokens and shared primitives are synced from the Amigo marketing site, then extended with application-grade patterns for internal products.

Fonts

| Font | Role | Source | | -------------------- | ------------------------ | ----------------------------------------- | | Flecha S | Display headlines, stats | Shipped as .woff2 in @amigo-ai/tokens | | Inter | Body text, buttons, UI | Google Fonts (auto-loaded in globals.css) | | ABC Diatype Mono | Uppercase labels, code | Shipped as .woff2 in @amigo-ai/tokens |

In Next.js apps, next/font overrides the CSS variables (--font-flecha, --font-inter, --font-diatype) for optimal loading.

Colors

| Token | Value | Use | | ------------------- | --------------------- | ------------------------------- | | amigo-blue | #083241 | Primary actions, links | | amigo-orange | #AA412A | CTA buttons | | amigo-green | #2c3827 | Secondary actions | | amigo-lavender | #C5BACE | Accent | | warm-1 → warm-6 | #F1EAE7 → #575452 | Neutral surfaces, text, borders |

Full semantic theme via CSS variables (--background, --foreground, --primary, --muted, etc.) with light defaults plus .dark / [data-theme="dark"] overrides.

Typography Scale

Responsive Tailwind tokens from text-hero (120px) down to text-caption-sm (11px), with semantic type-* classes:

type-display · type-h1 · type-h2 · type-h3 · type-h4 · type-subtitle · type-body · type-eyebrow · type-caption · type-mono · type-btn · type-blog-* · type-stat · type-quote-fluid

Effects

• Fluid spacing — clamp()-based tokens scaling from 375px to 1440px
• Border radius — 6px buttons, 20px cards
• Flat design — no shadows; use borders for elevation

Application Patterns

• Page scaffolding — PageContainer, PageSection, and ResourcePage extract the layout structure used by admin and dashboard flows
• Settings surfaces — ConfigPageContainer and ConfigurationSplitView provide a reusable split-view form layout
• Detail layouts — DetailPageWrapper, InfoCard, and StatCard cover common entity detail screens

Button Variants

| Variant | Purpose | | ------------- | --------------------- | | default | Standard (primary) | | secondary | Secondary actions | | outline | Bordered, transparent | | destructive | Dangerous actions | | ghost | Minimal / inline | | link | Text link style |

Components

Primitives (47)

Accordion · Alert · AlertDialog · AmigoWordmark · Avatar · Badge · Breadcrumb · Button · Calendar · Card · Chart · Checkbox · Collapsible · Command · CopyButton · Dialog · DropdownMenu · EnhancedTooltip · Form · FormActions · HoverCard · IconBox · InlineEditField · Input · Label · LiveIndicator · Logo · MonoLabel · Pagination · Popover · Progress · RadioGroup · Resizable · ScrollArea · Select · Separator · Sheet · Sidebar · Skeleton · Slider · Switch · Table · Tabs · Textarea · Toggle · ToggleGroup · Tooltip · Typography

Patterns (31)

AppShell · ConfigPageContainer · ConfigurationHeader · ConfigurationSplitView · ConfirmAlertDialog · DashboardGrid · DetailLayout · DetailPageWrapper · EmptyState · ErrorBoundary · ErrorState · FilterBar · FilterChip · FilterClear · FilterSearch · FormSection · InfoCard · KpiCard · LinedSection · LoadingState · LogoGrid · MetricCard · PageContainer · PageHeader · PageSection · PageShell · PageSkeleton · PropertiesPanel · ResourcePage · SectionHeader · SectionIntro · StatCard · StatusStrip · TablePage · Timeline · WizardShell

Accessibility

• WCAG 2.1 AA — all color pairings verified at 4.5:1+ contrast
• prefers-reduced-motion — all animations and transitions disabled
• Focus rings — focus-visible on every interactive component
• Screen readers — Radix UI provides full ARIA semantics out of the box
• aria-hidden on decorative icons

Development

pnpm install          # install deps
pnpm build            # build compatibility package
pnpm packages:build   # build split packages
pnpm typecheck        # type check
pnpm lint             # ESLint, zero warnings
pnpm format:check     # Prettier
pnpm test             # Vitest
pnpm changeset        # create a changeset

CI / CD

CI — 3 parallel jobs on every push and PR

| Job | What | | --------------------- | --------------------------------- | | Lint & Format | ESLint (zero warnings) + Prettier | | Build & Typecheck | Turborepo build + tsc | | Test | Vitest |

Release Process

This repo follows a standard Changesets release train for publishing public scoped packages to npm:

1. Every package change lands with a changeset file from pnpm changeset
2. Merging to main runs the Release workflow
3. Changesets opens or updates a single bot-managed PR: release: version packages
4. The workflow enables auto-merge on that PR after required checks pass
5. When the release PR merges, the workflow publishes packages to npm and creates GitHub Releases

Release Rules

• All publishable package changes require a changeset in the same PR
• Published package versions must stay coordinated across the split package surface
• main is the only publishing branch
• CI must stay green on both the feature PR and the generated release PR

Day-To-Day Release Flow

• Feature PR: add a changeset whenever package consumers should receive a new version
• Merge to main: the release workflow opens or refreshes the release PR
• Release PR: review the generated version/changelog diff if needed, then let auto-merge complete once checks pass
• Publish: the merge of that release PR publishes @amigo-ai/* packages and creates GitHub Releases
• Consume: downstream apps update to the new version from npm

Publishing

npm login
pnpm build
pnpm packages:build
pnpm typecheck
pnpm test

To release a new version with Changesets:

pnpm changeset
pnpm version-packages
pnpm release

For a first public publish of a scoped package, npm requires public access. This repo is configured for that via publishConfig.access and Changesets access: public.

Tooling

| Tool | Purpose | | ----------------------------------------------------------------------------------------------------- | --------------------------------------------- | | pnpm + Turborepo | Monorepo builds with cross-package caching | | tsup | ESM + CJS dual output with .d.ts generation | | Radix UI | Accessible, unstyled component primitives | | CVA | Type-safe component variants | | tailwindcss-animate | Data-attribute animations for Radix overlays | | Vitest + Testing Library | Component + utility tests | | Changesets | Automated versioning + changelogs | | Husky + lint-staged | Pre-commit lint + format | | Dependabot | Weekly dependency updates (grouped) |

Architecture

src/
  tokens/            colors, typography, spacing, animations, Tailwind preset
  utils/             cn() and badge variant mappers
  primitives/        Radix-based components and building blocks
  patterns/          application layout and page patterns
  globals.css        CSS variables and brand fonts
  fonts/             bundled Flecha S and Diatype Mono assets
  index.ts           compatibility package barrel for @amigo-ai/ui

packages/
  tokens/            @amigo-ai/tokens package wrapper
  utils/             @amigo-ai/ui-utils package wrapper
  primitives/        @amigo-ai/primitives package wrapper
  patterns/          @amigo-ai/patterns package wrapper
  design-review/     @amigo-ai/design-review package wrapper

License

Published to npm as a public scoped package.