Skip to content

Latest commit

 

History

History
260 lines (200 loc) · 8.28 KB

DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md

File metadata and controls

260 lines (200 loc) · 8.28 KB

Design System Agent Instructions

CRITICAL: These instructions are MANDATORY for all UI/frontend work. Follow exactly as written.

Pre-Work Checklist

Before ANY UI/component work:

  1. Check MCP availability (recommended):

    • Search for mcp__storybook__* tools
    • Search for mcp__figma__* tools
    • If available: Use them to get design context and component examples
    • If missing: Continue with pattern discovery via code exploration

  2. Load design context (if MCPs available):

    Call: mcp__storybook__get-ui-building-instructions
Call: mcp__figma__get_design_context (if working from designs)

  3. Read existing patterns:

    • The Storybook MCP provides component examples and usage patterns
    • Find similar widgets/components in the project: src/web/src/**/*{keyword}*.{tsx,ts}
    • Use Grep to find token usage patterns: theme\.color\.|theme\.space\.|theme\.radius\.
    • Read 1-2 similar components in the project to understand patterns
    • DO NOT read more than 3 files for context

Strict Rules (Zero Tolerance)

1. Design Tokens ONLY

NEVER hardcode values. Use theme.* exclusively:

// ❌ FORBIDDEN
color: '#1976d2'
padding: '8px'
border-radius: '4px'
font-size: '14px'

// ✅ REQUIRED
color: ${theme.color.primary.action}
padding: ${theme.space.space8}
border-radius: ${theme.radius.radius8}
// For typography, prefer using <Text> or <Heading> components

Token Reference (understand the patterns):

  • Colors: theme.color.{category}.{property}
    • Example categories: neutral, primary, primaryBlack, success, warning, danger
    • Example properties: text, textMuted, background, backgroundSubtle, action, actionHover, border, icon, etc.
  • Spacing: theme.space.space{N}
    • Examples: space8, space16, space24 (incremental values available)
  • Radius: theme.radius.radius{N}
    • Examples: radius4, radius6, radius8, radius12, radiusFull
  • Shadows: theme.shadow.{name}
    • Examples: shadow1, shadow2, shadow3, shadowActive

To discover available tokens: Use Storybook MCP or Grep existing usage in src/web/src

2. Component Imports

// ✅ Import from ui-library
import { Button, Badge, Chip } from '@apify/ui-library';

// ❌ NEVER create duplicate components
// ❌ NEVER import from relative paths outside ui-library

3. Styled Components Pattern

import styled from 'styled-components';
import { theme } from '@apify/ui-library';

// ✅ Correct pattern
const StyledComponent = styled.div<{ $variant?: string }>`
    color: ${theme.color.neutral.text};
    padding: ${theme.space.space16};

    ${({ $variant }) => $variant === 'primary' && css`
        background: ${theme.color.primary.background};
    `}
`;

// Note: Use $ prefix for transient props ($variant, $isActive, etc.)

4. Component Structure (Strict Order)

// 1. Imports (grouped)
import { forwardRef } from 'react';
import styled from 'styled-components';
import { theme } from '@apify/ui-library';

// 2. Constants & Types
export const COMPONENT_VARIANTS = { ... } as const;
type ComponentVariants = ValueOf<typeof COMPONENT_VARIANTS>;

// 3. Styled Components
const StyledWrapper = styled.div`...`;

// 4. Component Implementation
export const Component = forwardRef<HTMLElement, Props>((props, ref) => {
    // implementation
});

// 5. Display Name
Component.displayName = 'Component';

5. Color Usage Rules

Semantic Naming Required:

  • Text: theme.color.{category}.text, .textMuted, .textSubtle, .textDisabled
  • Backgrounds: theme.color.{category}.background, .backgroundSubtle, .backgroundMuted
  • Interactive: theme.color.{category}.action, .actionHover, .actionActive
  • Borders: theme.color.{category}.border, .separatorSubtle, .fieldBorder
  • Icons: theme.color.{category}.icon, .iconSubtle, .iconDisabled

State Variants:

// Default → Hover → Active states
background: ${theme.color.primary.action};
&:hover { background: ${theme.color.primary.actionHover}; }
&:active { background: ${theme.color.primary.actionActive}; }

6. Spacing Rules

  • Gaps between elements: space4, space8, space12
  • Component padding: space8, space12, space16
  • Section margins: space16, space24, space32
  • Large layouts: space40, space64, space80

NEVER use arbitrary values like gap: 10px - round to nearest token.

7. Typography Rules

// ✅ Use Text or Heading components from ui-library
import { Text, Heading } from '@apify/ui-library';

// Text component props: type, size, weight
<Text type="body" size="regular" weight="normal">Content here</Text>

// Heading component props: type
<Heading type="titleL">Title here</Heading>

// ❌ NEVER use typography tokens directly
// ❌ NEVER hardcode font properties

Verification Protocol (Before Submitting)

Run this mental checklist:

  1. Token Audit: Search your code for:

    • Regex: ['"]#[0-9a-fA-F]{3,8}['"] → Should be ZERO matches
    • Regex: ['"][0-9]+px['"] → Should be ZERO matches (except in exceptional cases)
    • All color:, background:, padding:, margin:, gap: use theme.*

  2. Import Check:

    • All styled-components import theme from @apify/ui-library
    • No duplicate component implementations

  3. Pattern Match:

    • Compare your component structure to similar existing components
    • Follow same prop naming conventions
    • Use same variant patterns

Common Pitfalls (Avoid These)

  1. ❌ Mixing hardcoded and token values

    // ❌ WRONG
padding: ${theme.space.space16} 10px;

// ✅ CORRECT
padding: ${theme.space.space16} ${theme.space.space10};

  2. ❌ Using non-existent color properties

    // ❌ WRONG
theme.color.neutral.textLight // doesn't exist
theme.color.primary.main // doesn't exist

// ✅ CORRECT
theme.color.neutral.textMuted // use actual property names
theme.color.primary.action // use actual property names

  3. ❌ Not using available MCPs

    • If Storybook or Figma MCPs are available, use them
    • They provide valuable context and patterns

  4. ❌ Over-reading for context

    • Read max 3 similar components
    • Don't read entire directories
    • Use Grep to find specific patterns

Figma Integration Workflow

When user provides Figma design:

  1. Get design context:

    mcp__figma__get_design_context (with Figma URL)

  2. Extract design tokens:

    • Colors → Map to theme.color.*
    • Spacing → Map to theme.space.*

  3. Get screenshots if needed:

    mcp__figma__get_screenshot (for visual reference)

  4. Verify variable mappings:

    mcp__figma__get_variable_defs (to see Figma variables)

Quick Reference Card

Property Token Pattern Example
Text color theme.color.{cat}.{prop} theme.color.neutral.text
Background theme.color.{cat}.{prop} theme.color.primary.background
Padding/Margin theme.space.space{N} theme.space.space16
Gap theme.space.space{N} theme.space.space8
Border radius theme.radius.radius{N} theme.radius.radius8
Shadow theme.shadow.{name} theme.shadow.shadow2
Typography <Text> or <Heading> components <Text type="body" size="regular">

Note: Use Storybook MCP or Grep (src/web/src) to discover all available token values.

Error Recovery

If you realize you used hardcoded values:

  1. Immediately stop
  2. List all violations
  3. Fix ALL violations before proceeding
  4. Re-verify using audit checklist

Summary: The Non-Negotiables

  1. ✅ Check MCP availability and use if available (recommended)
  2. ✅ Use theme.* tokens for ALL styling values (colors, spacing, radius, shadows)
  3. ✅ Use <Text> and <Heading> components for typography (not tokens)
  4. ✅ Import components from @apify/ui-library
  5. ✅ Follow existing component patterns (read 1-3 examples)
  6. ✅ Use semantic color naming (category.property)
  7. ✅ Verify zero hardcoded values before submitting
  8. ❌ NEVER hardcode colors (#hex or rgb)
  9. ❌ NEVER hardcode spacing (Npx values)
  10. ❌ NEVER create duplicate components

Enforcement: Any UI code not following these rules must be rejected and refactored immediately.