Design System Guidelines

This document defines the consistent design system used in ACQM to ensure a uniform UI experience throughout the application.

1. Design Principles

Consistency

• All components use the same design tokens
• Styles are centralized and reusable
• Behavior is predictable throughout the application

Scalability

• The design system can be easily extended with new components
• Tokens can be modified centrally
• Support for themes and customizations

Accessibility

• All components comply with WCAG standards
• Focus management and keyboard navigation
• Complete screen reader support

2. Design System Structure

src/
├── lib/
│   ├── design-tokens.ts          # Centralized design tokens
│   └── design-system-utils.ts    # Styling utilities
├── contexts/
│   └── DesignSystemContext.tsx   # Design system context
└── components/
    └── design-system/
        ├── ConsistentButton.tsx   # Consistent buttons
        ├── ConsistentCard.tsx     # Consistent cards
        ├── ConsistentInput.tsx    # Consistent inputs
        └── DesignSystemShowcase.tsx # Design system showcase

3. Design Tokens

Color Tokens (HSL Format)

/* Primary Colors */
--primary: 221 83% 53%;
--primary-foreground: 210 40% 98%;

/* Secondary Colors */
--secondary: 210 40% 96%;
--secondary-foreground: 222.2 84% 4.9%;

/* Semantic Colors */
--destructive: 0 84% 60%;
--success: 142 76% 36%;
--warning: 48 96% 53%;

Brand Colors

const BRAND_COLORS = {
  primary: '#DB5151',    // Brand red
  success: '#33B36B',    // Success green
  warning: '#FC9231',    // Warning orange
  info: '#3D7A81',       // Info teal
  destructive: '#F03D3D', // Error red
}

Design Tokens Reference

Token	Value
gray-50	#F5F7FA
gray-100	#EEF1F6
gray-200	#E0E5EB
gray-300	#CAD0D9
gray-400	#9CA3AF
gray-500	#6C727F
gray-600	#4E5562
gray-700	#333D4C
gray-800	#1D2735
gray-900	#111827
gray-950	#030712
primary	#DB5151
danger	#F03D3D
success	#33B36B
warning	#FC9231
info	#3D7A81

Typography Scale

• Headings: font-sans with font-semibold
• Body: text-sm or text-base
• Captions: text-xs with text-muted-foreground

4. Component Patterns

Form Components

// Standard form pattern
<Form {...form}>
  <FormField
    control={form.control}
    name="fieldName"
    render={({ field }) => (
      <FormItem>
        <FormLabel>Field Label</FormLabel>
        <FormControl>
          <Input placeholder="Enter value..." {...field} />
        </FormControl>
        <FormMessage />
      </FormItem>
    )}
  />
</Form>

Table Components

// Data table pattern
<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Column 1</TableHead>
      <TableHead>Column 2</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    {data.map((item) => (
      <TableRow key={item.id}>
        <TableCell>{item.name}</TableCell>
        <TableCell>{item.value}</TableCell>
      </TableRow>
    ))}
  </TableBody>
</Table>

Modal/Dialog Pattern

<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Open Dialog</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Dialog Title</DialogTitle>
      <DialogDescription>Description text</DialogDescription>
    </DialogHeader>
    {/* Content */}
    <DialogFooter>
      <Button type="submit">Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

Button Variants

• default: Primary actions
• secondary: Secondary actions
• outline: Tertiary actions
• ghost: Minimal actions
• destructive: Delete/remove actions

Responsive Design

• Mobile-first approach with Tailwind breakpoints
• sm: (640px+), md: (768px+), lg: (1024px+), xl: (1280px+)

5. Typography Tokens

const TYPOGRAPHY = {
  fontFamily: {
    primary: ['Onest', 'system-ui', 'sans-serif'],
  },
  fontSize: {
    xs: ['0.75rem', { lineHeight: '1rem' }],
    sm: ['0.875rem', { lineHeight: '1.25rem' }],
    // ... other sizes
  }
}

Spacing Scale

const SPACING = {
  0: '0',
  1: '0.25rem',  // 4px
  2: '0.5rem',   // 8px
  4: '1rem',     // 16px
  // ... other values
}

6. Consistent Components

Using Consistent Components

// ❌ DON'T - hardcoded styles
<button className="bg-blue-500 hover:bg-blue-600 px-4 py-2 rounded">
  Click me
</button>

// ✅ DO - consistent components
<ConsistentButton variant="default" size="md">
  Click me
</ConsistentButton>

// Or with hooks
const { button } = useComponentStyle();
<button className={button('default', 'md')}>
  Click me
</button>

Button Variants

// Predefined buttons
<PrimaryButton>Primary Action</PrimaryButton>
<SecondaryButton>Secondary Action</SecondaryButton>
<OutlineButton>Outline Action</OutlineButton>
<DestructiveButton>Delete Action</DestructiveButton>

// Or with custom variants
<ConsistentButton variant="ghost" size="lg">
  Custom Button
</ConsistentButton>

Consistent Cards

// Predefined cards
<ConsistentCard>Default Card</ConsistentCard>
<HoverCard>Card with Hover Effects</HoverCard>
<ElevatedCard>Card with Elevated Shadow</ElevatedCard>
<OutlinedCard>Card with Thick Border</OutlinedCard>

Consistent Inputs

// Inputs with variants
<ConsistentInput placeholder="Default input" />
<FilledInput placeholder="Filled input" />
<OutlinedInput placeholder="Outlined input" />
<GhostInput placeholder="Ghost input" />

// Inputs with state
<ErrorInput placeholder="Error state" />
<SuccessInput placeholder="Success state" />
<WarningInput placeholder="Warning state" />

7. Design System Utilities

Styling Hooks

import { useDesignSystem, useComponentStyle } from '@/contexts/DesignSystemContext';

function MyComponent() {
  const { tokens, getColor, getSpacing } = useDesignSystem();
  const { button, card, input } = useComponentStyle();
  
  return (
    <div style={{ 
      backgroundColor: getColor('colors.primary'),
      padding: getSpacing('4')
    }}>
      <button className={button('default', 'md')}>
        Styled Button
      </button>
    </div>
  );
}

Direct Utilities

import { designSystemUtils } from '@/lib/design-system-utils';

// Colors
const primaryColor = designSystemUtils.getColor('colors.primary');

// Spacing
const padding = designSystemUtils.getSpacing('4');

// Component styling
const buttonStyles = designSystemUtils.buildButtonStyles('default', 'md');
const cardStyles = designSystemUtils.buildCardStyles('hover');

8. Customization and Extension

Adding New Tokens

// In design-tokens.ts
export const CUSTOM_TOKENS = {
  // Add new colors
  colors: {
    ...BRAND_COLORS,
    custom: '#FF6B6B',
  },
  // Add new spacing values
  spacing: {
    ...SPACING,
    '18': '4.5rem',
  }
};

Adding New Components

// Create a new consistent component
export const ConsistentModal: React.FC<ModalProps> = ({
  variant = 'default',
  size = 'md',
  ...props
}) => {
  const { modal } = useComponentStyle();
  const consistentClasses = modal(variant, size);
  
  return (
    <Modal className={cn(consistentClasses, props.className)} {...props} />
  );
};

9. Best Practices

DO - What to do

• ✅ Always use consistent components
• ✅ Apply design tokens for colors, spacing, typography
• ✅ Test components in different contexts
• ✅ Document new components added
• ✅ Maintain consistency throughout the application

DON'T - What NOT to do

• ❌ Don't hardcode styles in components
• ❌ Don't create new variants without adding them to the design system
• ❌ Don't ignore existing design tokens
• ❌ Don't create components that don't follow the design system

10. Testing the Design System

Live Interactive Demo

Visit the live demo page to test all components interactively:

• URL: http://localhost:8080/design-system
• Features: All button variants, card styles, input states, badges, and complete form example

Showcase Component

Use DesignSystemShowcase to test all components:

import { DesignSystemShowcase } from '@/components/design-system/DesignSystemShowcase';

// Add to routing for testing
<Route path="/design-system" element={<DesignSystemShowcase />} />

Automated Checks

• Lint rules to prevent hardcoded styles
• TypeScript types for design tokens
• Unit tests for consistent components

11. Migrating Existing Components

Step by Step

1. Identify components with hardcoded styles
2. Replace with consistent components
3. Test visually that they look identical
4. Verify that functionality is preserved
5. Document the changes

Migration Example

// BEFORE
<div className="bg-white p-4 rounded-lg shadow-md hover:shadow-lg">
  <h3 className="text-lg font-semibold text-gray-900">Title</h3>
  <p className="text-gray-600">Description</p>
</div>

// AFTER
<ConsistentCard variant="hover">
  <ConsistentCardHeader>
    <ConsistentCardTitle>Title</ConsistentCardTitle>
  </ConsistentCardHeader>
  <ConsistentCardContent>
    <ConsistentCardDescription>Description</ConsistentCardDescription>
  </ConsistentCardContent>
</ConsistentCard>

12. Resources and References

Live Demo

• Design System Live Demo - Interactive component showcase

External Resources

• shadcn/ui Documentation
• Tailwind CSS Documentation
• Design Tokens Specification

13. Advanced Components (How It Works Style)

ConsistentHero

Hero section component with gradient backgrounds and trust indicators:

import { ConsistentHero } from '@/components/design-system/ConsistentHero';

<ConsistentHero
  eyebrow="Design System"
  title="Consistent UI Components"
  highlight="How It Works Style"
  description="Comprehensive design system with integrated styling patterns."
  primaryCta={{
    label: "Get Started",
    href: "/start",
    icon: ArrowRight,
  }}
  trustIndicators={[
    { icon: ShieldCheck, label: "Secure & Reliable" },
    { icon: Sparkles, label: "Vetted Components" },
  ]}
  stats={[
    { value: "50+", label: "Components", caption: "Ready to use" },
    { value: "100%", label: "Consistent", caption: "Design patterns" },
  ]}
/>

ConsistentJourneySection

Step-by-step journey with animated cards:

import { ConsistentJourneySection } from '@/components/design-system/ConsistentJourneyCard';

<ConsistentJourneySection
  title="How It Works"
  subtitle="Follow these steps to get started"
  steps={[
    {
      icon: Search,
      tag: "Step 1",
      title: "Discover",
      description: "Find what you need",
      highlights: ["Easy search", "Filter options", "Quick results"],
    },
    // ... more steps
  ]}
  cta={{
    title: "Ready to Start?",
    description: "Begin your journey today.",
    primaryLabel: "Get Started",
    primaryHref: "/start",
  }}
/>

ConsistentFeatureGrid

Feature showcase with hover effects:

import { ConsistentFeatureGrid } from '@/components/design-system/ConsistentFeatureGrid';

<ConsistentFeatureGrid
  title="Features"
  subtitle="Everything you need"
  features={[
    {
      icon: Users,
      title: "User-Centric",
      description: "Designed for users",
      highlights: ["Accessible", "Intuitive", "Fast"],
    },
    // ... more features
  ]}
  columns={3}
/>

ConsistentTabs

Tabbed interface with consistent styling:

import { ConsistentTabs } from '@/components/design-system/ConsistentTabs';

<ConsistentTabs
  tabs={[
    {
      value: "tab1",
      label: "Tab 1",
      content: <div>Tab 1 content</div>,
    },
    {
      value: "tab2", 
      label: "Tab 2",
      content: <div>Tab 2 content</div>,
    },
  ]}
/>

• WCAG Guidelines

---

Note: This design system is in constant evolution. All changes must be approved and documented according to these guidelines.