Design Integration

Design Integration

Overview

Detect the project's design system, embrace it fully, and extend it only through sanctioned channels. Never resist it, never overlook it, never rebuild what it already offers.

Core principle: When a project has a design system, every component you create must consume that system's primitives, tokens, and patterns. When no system exists, establish one before writing components.

No exceptions. No workarounds. No shortcuts.

The Prime Directive

NEVER REBUILD WHAT THE DESIGN SYSTEM ALREADY PROVIDES

If the system ships a <Dialog> component, use it. Do not fabricate your own. Do not wrap it in a container with overriding styles. Consume its variant API and extend only through its documented extension points.

When to Use

Mandatory when:

• Entering any existing codebase with a user interface
• Introducing new UI elements to an established application
• Growing a project's component library
• Initializing a new project that will have a UI layer

Specifically triggered by:

• Imports from @shadcn/ui, @mui/material, antd, @chakra-ui, or equivalents
• A components/ui directory containing base-level primitives
• Configuration files such as tailwind.config, theme.ts, or a design token file
• The need to add UI to a project with no system in place

The Entry Protocol

BEFORE authoring any UI component:

1. DETECT: What design system governs this project? (see Detection below)
2. STUDY: Read the system's component API for the element you are building
3. ASSESS: Does the system already provide this component?
   - Yes -> Consume it directly. Do NOT recreate it.
   - Partially -> Compose from existing primitives
   - No -> Build it adhering to the system's conventions
4. VALIDATE: Does your component feel native to the system?

Omit any step = fighting the system

Detection Sequence

digraph detect_system {
    rankdir=TB;
    start [label="New project or\nnew component", shape=doublecircle];
    check_deps [label="Inspect package.json\nfor UI frameworks", shape=box];
    known [label="Recognized design\nsystem present?", shape=diamond];
    check_code [label="Search source tree\nfor UI import patterns", shape=box];
    has_custom [label="Internal component\nlibrary found?", shape=diamond];
    check_tokens [label="Look for\ndesign token definitions", shape=box];
    has_tokens [label="Token file\ndetected?", shape=diamond];
    adopt_known [label="ADOPT\nUse the recognized system", shape=box, style=filled, fillcolor="#ccffcc"];
    adopt_internal [label="ADOPT\nFollow internal library conventions", shape=box, style=filled, fillcolor="#ccffcc"];
    bootstrap [label="BOOTSTRAP\nInitialize a design system", shape=box, style=filled, fillcolor="#ccccff"];
    extend_tokens [label="BUILD\non existing token foundation", shape=box, style=filled, fillcolor="#ccffcc"];

    start -> check_deps;
    check_deps -> known;
    known -> adopt_known [label="yes"];
    known -> check_code [label="no"];
    check_code -> has_custom;
    has_custom -> adopt_internal [label="yes\n(components/ui\nor equivalent)"];
    has_custom -> check_tokens [label="no"];
    check_tokens -> has_tokens;
    has_tokens -> extend_tokens [label="yes"];
    has_tokens -> bootstrap [label="no"];
}

Phase 1: Inspect Dependencies

Phase 2: Scan for Internal Components

Look for:

• components/ui/ directory (typical shadcn/ui layout)
• components/common/ or components/shared/
• Barrel re-exports from component directories
• Storybook stories (.stories.tsx)

Phase 3: Locate Design Tokens

Search for:

• tailwind.config.js/ts (Tailwind CSS theme customization)
• theme.ts or theme.js (custom theme objects)
• CSS custom properties defined on :root or [data-theme]
• tokens/ or design-tokens/ directories
• styles/variables.css or styles/tokens.css

Adoption: Operating Within an Existing System

Universal Principles

1. Consume the component API as-is. Do not add wrapper elements with inline overrides.
2. Use the system's variant mechanism. If it offers variant="danger", use that instead of manually overriding colors.
3. Use the system's sizing props. If it accepts size="sm", do not override with custom CSS.
4. Extend through the system's designated extension points. Not through CSS specificity wars.
5. Follow the system's directory conventions. If primitives live in components/ui/, new ones go there too.

shadcn/ui

Copy-and-customize components built on Radix UI + Tailwind CSS.

Conventions:

• Primitives in components/ui/ (base building blocks)
• Application components in components/ (composed from primitives)
• cn() helper for merging class strings
• cva() from class-variance-authority for variant definitions
• All styling through Tailwind utility classes

Adding a missing component:

npx shadcn@latest add [component-name]

Composing custom components:

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Badge } from "@/components/ui/badge"

export function ProjectCard({ project }) {
  return (
    <Card>
      <CardHeader><CardTitle>{project.title}</CardTitle></CardHeader>
      <CardContent>
        <Badge variant={project.live ? "default" : "secondary"}>
          {project.live ? "Live" : "Draft"}
        </Badge>
      </CardContent>
    </Card>
  )
}

Forbidden:

• Overriding shadcn styles with raw CSS files
• Rebuilding a component shadcn already provides
• Applying non-Tailwind styling alongside shadcn components
• Ignoring the cn() helper for conditional class composition

Material UI

Conventions:

• Theme defined via createTheme() in theme.ts
• Components imported from @mui/material
• Styling via sx prop or styled() API
• Global overrides through theme.components

Extending the theme:

const theme = createTheme({
  palette: { primary: { main: '#0d9488' } },
  components: {
    MuiButton: {
      defaultProps: { disableElevation: true },
      styleOverrides: { root: { textTransform: 'none', borderRadius: 8 } },
    },
  },
});

Ant Design

Conventions:

• Components imported from antd
• Theming through ConfigProvider + token system
• Global tokens via theme.token, per-component via theme.components

Forbidden: Direct overrides of .ant-* CSS classes or mixing Ant with a competing component library.

Tailwind CSS (Standalone, No Component Library)

When the project uses Tailwind without an accompanying component framework:

1. Inspect tailwind.config for custom theme extensions
2. Consume those values exclusively -- no arbitrary values
3. Replicate existing class patterns found in the codebase

Extension: Adding to an Existing System

When the system lacks a component you require:

Pre-Build Checklist

1. Search the system's documentation -- it may exist under a different name
2. Determine whether it can be assembled from existing primitives
3. Look for community plugins or extensions

Building a New Component Within the System

Align with the system's norms:

1. NAMING -- Follow the system's naming pattern (PascalCase components, kebab-case files, etc.)
2. API -- Follow the system's prop conventions (variant + size, cva, sx, etc.)
3. STYLING -- Use the same styling mechanism (Tailwind + cn(), sx prop, token references)
4. TOKENS -- Reference system token values, never raw literals
5. ACCESSIBILITY -- Reproduce the system's a11y patterns (ARIA attributes, keyboard navigation, focus management)