Cognite Design System

A comprehensive React component library built with TypeScript and Tailwind CSS, designed specifically for AI-generated applications that maintain consistent Cognite branding.

🎯 Purpose

This design system enables AI to easily generate applications with consistent look and feel based on Cognite branding. It provides a complete set of pre-built components that can be used to rapidly create professional applications.

📦 Installation

npm install @cognite/cogs.js-v2

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom

Setup Tailwind CSS

This design system uses Tailwind CSS v4. You have two setup options:

Option 1: Use the included styles (Recommended) Just import our pre-built styles - no additional Tailwind setup needed:

@import '@cognite/cogs.js-v2/styles';

Option 2: Configure Tailwind CSS v4 in your project If you want to customize or extend the design system:

/* In your main CSS file */
@import 'tailwindcss';
@import '@cognite/cogs.js-v2/styles';

⚠️ Important: Preventing CSS Purging

If you're using Tailwind CSS in your project, you need to prevent it from purging the CSS classes used by our components. The simplest solution is to include our package in your Tailwind content paths:

// tailwind.config.js
export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@cognite/cogs.js-v2/dist/**/*.{js,ts,jsx,tsx}',
  ],
  // ... rest of your config
}

Example configurations:

• Complete example - Full configuration with comments
• Minimal example - Simplest working configuration

Note: Our styles include @source "" which tells Tailwind to include all classes without purging, ensuring components always have proper styling.

🚀 Quick Start

import { Button, Card, Input } from '@cognite/cogs.js-v2';

function App() {
  return (
    <Card>
      <Input label="Email" type="email" />
      <Button variant="primary">Submit</Button>
    </Card>
  );
}

🔧 Troubleshooting

Components have no styling

If your components appear unstyled, this is likely due to Tailwind CSS purging the component classes. Add our package to your Tailwind content paths:

// tailwind.config.js
export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@cognite/cogs.js-v2/dist/**/*.{js,ts,jsx,tsx}', // Add this line
  ],
}

Classes not found errors

If you see console warnings about missing Tailwind classes:

1. Make sure you've imported our styles: @import '@cognite/cogs.js-v2/styles';
2. Add our package to your Tailwind content paths (see above)
3. Restart your development server after making Tailwind config changes

TypeScript errors

Make sure you have the correct TypeScript configuration and that React types are installed:

npm install --save-dev @types/react @types/react-dom

🤖 AI Usage Guide

This package includes a comprehensive AI usage guide to help AI systems generate consistent applications:

Accessing the Guide

As a file:

# After installation, the guide is available at:
node_modules/cognite-design-system/dist/AI_USAGE_GUIDE.md

Direct import:

// Import the guide file directly
import guideContent from 'cognite-design-system/ai-guide';

📦 Components

Typography

• Heading - Semantic headings (H1-H6) with consistent styling
• Text - Body text with various sizes and weights
• Label - Form labels with required indicators
• Code - Inline and block code formatting

Buttons

• Button - Primary action buttons with multiple variants
• IconButton - Compact buttons with icons only
• ButtonGroup - Grouped button collections

Forms

• Input - Text inputs with validation states
• SearchInput - Specialized search input with clear functionality
• Select - Dropdown selections
• Checkbox - Single and grouped checkboxes
• Radio - Radio button groups
• Switch - Toggle switches
• Textarea - Multi-line text inputs

Layout

• Container - Responsive content containers
• Card - Content cards with headers and footers
• Grid - Responsive grid layouts
• Stack - Flexible stacking layouts (HStack/VStack)
• Divider - Content separators

Navigation

• Navbar - Application navigation bars
• Sidebar - Collapsible side navigation
• Breadcrumbs - Navigation breadcrumbs
• Tabs - Tabbed content navigation

Feedback

• Alert - Status messages and notifications
• Badge - Status indicators and labels
• NotificationBadge - Count indicators
• Loading - Loading states and skeletons
• Toast - Temporary notifications
• Modal - Dialog overlays

Data Display

• Table - Data tables with sorting and selection
• List - Item lists with various layouts
• DescriptionList - Key-value pair displays
• Stats - Statistical data display
• KPICard - Key performance indicator cards
• Avatar - User profile images and initials
• AvatarGroup - Multiple avatar displays

🎨 Design Tokens

The design system uses Cognite's color palette:

Colors

• Sapphire - Primary brand color
• Emerald - Success states
• Ruby - Error states
• Amber - Warning states
• Turquoise - Info states
• Amethyst - Accent color
• Aquamarine - Secondary accent
• Canary - Highlight color
• Onyx - Neutral grays

Typography

• Font Family: Inter (primary), Source Code Pro (monospace)
• Sizes: body-xxsmall, body-small, body-medium, body-large, heading-1 through heading-6

Spacing & Layout

• Border Radius: xs (2px) to 4xl (32px)
• Container: Responsive with max-widths
• Grid: 12-column responsive grid system

🤖 AI Usage Guidelines

When using this design system for AI-generated applications:

1. Component Selection

// ✅ Good - Use semantic components
<Card>
  <CardHeader title="User Profile" />
  <CardContent>
    <Avatar name="John Doe" />
    <Text>Software Engineer</Text>
  </CardContent>
</Card>

// ❌ Avoid - Don't create custom styled divs
<div className="bg-white p-4 rounded shadow-sm">
  <div className="font-bold">User Profile</div>
  <div className="w-10 h-10 rounded-full bg-gray-300"></div>
</div>

2. Consistent Patterns

// ✅ Form layouts
<VStack gap="md">
  <Input label="Email" required />
  <Input label="Password" type="password" required />
  <Button variant="primary" fullWidth>Sign In</Button>
</VStack>

// ✅ Data display
<StatsGroup 
  columns={3}
  stats={[
    { label: "Total Users", value: "1,234", change: { value: "+12%", type: "increase" } },
    { label: "Revenue", value: "$45,678", change: { value: "+8%", type: "increase" } },
    { label: "Conversion", value: "3.2%", change: { value: "-2%", type: "decrease" } }
  ]}
/>

3. Responsive Design

// ✅ Use responsive props
<Grid 
  cols={1} 
  responsive={{ md: 2, lg: 3 }}
  gap="md"
>
  <Card>Content 1</Card>
  <Card>Content 2</Card>
  <Card>Content 3</Card>
</Grid>

4. Accessibility

// ✅ Include proper labels and ARIA attributes
<Modal 
  isOpen={isOpen} 
  onClose={onClose}
  title="Confirm Action"
  description="This action cannot be undone"
>
  <Text>Are you sure you want to delete this item?</Text>
  <ModalFooter>
    <Button variant="outline" onClick={onClose}>Cancel</Button>
    <Button variant="destructive" onClick={onConfirm}>Delete</Button>
  </ModalFooter>
</Modal>

📱 Common Patterns

Dashboard Layout

<Container maxWidth="7xl">
  <VStack gap="lg">
    <Navbar>
      <NavbarBrand title="Cognite App" />
      <NavbarMenu>
        <NavbarItem href="/dashboard" active>Dashboard</NavbarItem>
        <NavbarItem href="/analytics">Analytics</NavbarItem>
      </NavbarMenu>
    </Navbar>
    
    <HStack gap="lg" align="start">
      <Sidebar width="md">
        <SidebarSection title="Main">
          <SidebarItem icon={<DashboardIcon />} active>Dashboard</SidebarItem>
          <SidebarItem icon={<UsersIcon />}>Users</SidebarItem>
        </SidebarSection>
      </Sidebar>
      
      <VStack gap="md" className="flex-1">
        <StatsGroup columns={4} variant="cards" stats={stats} />
        <Grid cols={2} gap="md">
          <Card>
            <CardHeader title="Recent Activity" />
            <CardContent>
              <List>
                {activities.map(activity => (
                  <ListItem key={activity.id} {...activity} />
                ))}
              </List>
            </CardContent>
          </Card>
          <Card>
            <CardHeader title="Performance" />
            <CardContent>
              <KPICard 
                title="Monthly Growth"
                value="24.5%"
                progress={75}
                trend={{ value: "+5.2%", type: "up", period: "vs last month" }}
                status="success"
              />
            </CardContent>
          </Card>
        </Grid>
      </VStack>
    </HStack>
  </VStack>
</Container>

Form Layout

<Card maxWidth="md">
  <CardHeader title="Create Account" description="Fill in your details below" />
  <CardContent>
    <VStack gap="md">
      <HStack gap="md">
        <Input label="First Name" required />
        <Input label="Last Name" required />
      </HStack>
      <Input label="Email" type="email" required />
      <Input label="Password" type="password" required />
      <CheckboxGroup label="Preferences">
        <Checkbox label="Email notifications" />
        <Checkbox label="SMS notifications" />
      </CheckboxGroup>
      <Button variant="primary" fullWidth>Create Account</Button>
    </VStack>
  </CardContent>
</Card>

Data Table

<Card>
  <CardHeader title="Users" action={<Button>Add User</Button>} />
  <CardContent>
    <Table
      columns={[
        { key: 'name', title: 'Name', dataIndex: 'name' },
        { key: 'email', title: 'Email', dataIndex: 'email' },
        { key: 'role', title: 'Role', dataIndex: 'role', 
          render: (role) => <Badge variant="primary">{role}</Badge> },
        { key: 'status', title: 'Status', dataIndex: 'status',
          render: (status) => <Badge variant={status === 'active' ? 'success' : 'error'}>{status}</Badge> }
      ]}
      data={users}
      rowSelection={{
        selectedRowKeys,
        onChange: setSelectedRowKeys
      }}
    />
  </CardContent>
</Card>

🎯 Best Practices for AI

1. Always use design system components instead of custom HTML/CSS
2. Follow consistent spacing using the gap props (xs, sm, md, lg, xl)
3. Use semantic color variants (primary, success, warning, error) over specific colors
4. Implement proper loading states for async operations
5. Include error handling with appropriate error messages
6. Make forms accessible with proper labels and validation
7. Use responsive layouts that work on all screen sizes
8. Follow the component composition patterns shown in examples

🔧 Customization

The design system uses CSS custom properties for theming. Colors can be customized by updating the CSS variables:

:root {
  --ds-color-sapphire-500: #your-primary-color;
  --ds-color-emerald-500: #your-success-color;
  /* ... other color overrides */
}

📚 TypeScript Support

All components are fully typed with TypeScript interfaces. Import types as needed:

import { ButtonProps, CardProps, InputProps } from '@cognite/design-system';

🚀 Development

Building the Library

# Build for production
npm run build

# Build and watch for changes
npm run build:lib -- --watch

Publishing

# Build and publish to npm
npm run prepublishOnly
npm publish --access public

🤝 Contributing

1. Follow the existing component patterns
2. Use TypeScript for all components
3. Include comprehensive prop documentation
4. Test components in Storybook
5. Follow Cognite's design principles

📄 License

MIT License - see LICENSE file for details.

This design system provides everything needed to create consistent, professional applications that align with Cognite's brand guidelines while being optimized for AI-driven development workflows.