AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

ui-design-system

Use when building a design system: tokens, component docs, responsive scales or developer handoff. Generates tokens with design_token_generator.py.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--ui-design-system at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 6

references/developer-handoff.md

Developer Handoff Guide

Reference for integrating design tokens into development workflows and design tool collaboration.


Table of Contents


Export Formats

JSON (Recommended for Most Projects)

File: design-tokens.json

{
  "meta": {
    "version": "1.0.0",
    "style": "modern",
    "generated": "2024-01-15"
  },
  "colors": {
    "primary": {
      "50": "#E6F2FF",
      "100": "#CCE5FF",
      "500": "#0066CC",
      "900": "#002855"
    }
  },
  "typography": {
    "fontFamily": {
      "sans": "Inter, system-ui, sans-serif",
      "mono": "Fira Code, monospace"
    },
    "fontSize": {
      "xs": "10px",
      "sm": "13px",
      "base": "16px",
      "lg": "20px"
    }
  },
  "spacing": {
    "0": "0px",
    "1": "4px",
    "2": "8px",
    "4": "16px"
  }
}

Use Case: JavaScript/TypeScript projects, build tools, Figma plugins

CSS Custom Properties

File: design-tokens.css

:root {
  /* Colors */
  --color-primary-50: #E6F2FF;
  --color-primary-100: #CCE5FF;
  --color-primary-500: #0066CC;
  --color-primary-900: #002855;

  /* Typography */
  --font-family-sans: Inter, system-ui, sans-serif;
  --font-family-mono: Fira Code, monospace;
  --font-size-xs: 10px;
  --font-size-sm: 13px;
  --font-size-base: 16px;
  --font-size-lg: 20px;

  /* Spacing */
  --spacing-0: 0px;
  --spacing-1: 4px;
  --spacing-2: 8px;
  --spacing-4: 16px;
}

Use Case: Plain CSS, CSS-in-JS, any web project

SCSS Variables

File: _design-tokens.scss

// Colors
$color-primary-50: #E6F2FF;
$color-primary-100: #CCE5FF;
$color-primary-500: #0066CC;
$color-primary-900: #002855;

// Typography
$font-family-sans: Inter, system-ui, sans-serif;
$font-family-mono: Fira Code, monospace;
$font-size-xs: 10px;
$font-size-sm: 13px;
$font-size-base: 16px;
$font-size-lg: 20px;

// Spacing
$spacing-0: 0px;
$spacing-1: 4px;
$spacing-2: 8px;
$spacing-4: 16px;

// Maps for programmatic access
$colors-primary: (
  '50': $color-primary-50,
  '100': $color-primary-100,
  '500': $color-primary-500,
  '900': $color-primary-900
);

Use Case: SASS/SCSS pipelines, component libraries


Integration Patterns

Pattern 1: CSS Variables (Universal)

Works with any framework or vanilla CSS.

/* Import tokens */
@import 'design-tokens.css';

/* Use in styles */
.button {
  background-color: var(--color-primary-500);
  padding: var(--spacing-2) var(--spacing-4);
  font-size: var(--font-size-base);
  border-radius: var(--radius-md);
}

.button:hover {
  background-color: var(--color-primary-600);
}

Pattern 2: JavaScript Theme Object

For CSS-in-JS libraries (styled-components, Emotion, etc.)

// theme.ts
import tokens from './design-tokens.json';

export const theme = {
  colors: {
    primary: tokens.colors.primary,
    secondary: tokens.colors.secondary,
    neutral: tokens.colors.neutral,
    semantic: tokens.colors.semantic
  },
  typography: {
    fontFamily: tokens.typography.fontFamily,
    fontSize: tokens.typography.fontSize,
    fontWeight: tokens.typography.fontWeight
  },
  spacing: tokens.spacing,
  shadows: tokens.shadows,
  radii: tokens.borders.radius
};

export type Theme = typeof theme;
// styled-components usage
import styled from 'styled-components';

const Button = styled.button`
  background: ${({ theme }) => theme.colors.primary['500']};
  padding: ${({ theme }) => theme.spacing['2']} ${({ theme }) => theme.spacing['4']};
  font-size: ${({ theme }) => theme.typography.fontSize.base};
`;

Pattern 3: Tailwind Config

// tailwind.config.js
const tokens = require('./design-tokens.json');

module.exports = {
  theme: {
    colors: {
      primary: tokens.colors.primary,
      secondary: tokens.colors.secondary,
      neutral: tokens.colors.neutral,
      success: tokens.colors.semantic.success,
      warning: tokens.colors.semantic.warning,
      error: tokens.colors.semantic.error
    },
    fontFamily: {
      sans: [tokens.typography.fontFamily.sans],
      serif: [tokens.typography.fontFamily.serif],
      mono: [tokens.typography.fontFamily.mono]
    },
    spacing: {
      0: tokens.spacing['0'],
      1: tokens.spacing['1'],
      2: tokens.spacing['2'],
      // ... etc
    },
    borderRadius: tokens.borders.radius,
    boxShadow: tokens.shadows
  }
};

Framework Setup

React + CSS Variables

// App.tsx
import './design-tokens.css';
import './styles.css';

function App() {
  return (
    <button className="btn btn-primary">
      Click me
    </button>
  );
}
/* styles.css */
.btn {
  padding: var(--spacing-2) var(--spacing-4);
  font-size: var(--font-size-base);
  font-weight: var(--font-weight-medium);
  border-radius: var(--radius-md);
  transition: background-color var(--animation-duration-fast);
}

.btn-primary {
  background: var(--color-primary-500);
  color: var(--color-surface-background);
}

.btn-primary:hover {
  background: var(--color-primary-600);
}

React + styled-components

// ThemeProvider.tsx
import { ThemeProvider } from 'styled-components';
import { theme } from './theme';

export function AppThemeProvider({ children }) {
  return (
    <ThemeProvider theme={theme}>
      {children}
    </ThemeProvider>
  );
}
// Button.tsx
import styled from 'styled-components';

export const Button = styled.button<{ variant?: 'primary' | 'secondary' }>`
  padding: ${({ theme }) => `${theme.spacing['2']} ${theme.spacing['4']}`};
  font-size: ${({ theme }) => theme.typography.fontSize.base};
  border-radius: ${({ theme }) => theme.radii.md};

  ${({ variant = 'primary', theme }) => variant === 'primary' && `
    background: ${theme.colors.primary['500']};
    color: ${theme.colors.surface.background};

    &:hover {
      background: ${theme.colors.primary['600']};
    }
  `}
`;

Vue + CSS Variables

<!-- App.vue -->
<template>
  <button class="btn btn-primary">Click me</button>
</template>

<style>
@import './design-tokens.css';

.btn {
  padding: var(--spacing-2) var(--spacing-4);
  font-size: var(--font-size-base);
  border-radius: var(--radius-md);
}

.btn-primary {
  background: var(--color-primary-500);
  color: var(--color-surface-background);
}
</style>

Next.js + Tailwind

// tailwind.config.js
const tokens = require('./design-tokens.json');

module.exports = {
  content: ['./app/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: tokens.colors,
      fontFamily: {
        sans: tokens.typography.fontFamily.sans.split(', ')
      }
    }
  }
};
// page.tsx
export default function Page() {
  return (
    <button className="bg-primary-500 hover:bg-primary-600 px-4 py-2 rounded-md text-white">
      Click me
    </button>
  );
}

Design Tool Integration

Figma

Option 1: Tokens Studio Plugin

  1. Install "Tokens Studio for Figma" plugin
  2. Import design-tokens.json
  3. Tokens sync automatically with Figma styles

Option 2: Figma Variables (Native)

  1. Open Variables panel
  2. Create collections matching token structure
  3. Import JSON via plugin or API

Sync Workflow:

design_token_generator.py
        ↓
design-tokens.json
        ↓
Tokens Studio Plugin
        ↓
Figma Styles & Variables

Storybook

// .storybook/preview.js
import '../design-tokens.css';

export const parameters = {
  backgrounds: {
    default: 'light',
    values: [
      { name: 'light', value: '#FFFFFF' },
      { name: 'dark', value: '#111827' }
    ]
  }
};
// Button.stories.tsx
import { Button } from './Button';

export default {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost']
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg']
    }
  }
};

export const Primary = {
  args: {
    variant: 'primary',
    children: 'Button'
  }
};

Design Tool Comparison

| Tool | Token Format | Sync Method | |------|--------------|-------------| | Figma | JSON | Tokens Studio plugin / Variables | | Sketch | JSON | Craft / Shared Styles | | Adobe XD | JSON | Design Tokens plugin | | InVision DSM | JSON | Native import | | Zeroheight | JSON/CSS | Direct import |


Handoff Checklist

Token Generation

  • [ ] Brand color defined
  • [ ] Style selected (modern/classic/playful)
  • [ ] Tokens generated: python scripts/design_token_generator.py "#0066CC" modern
  • [ ] All formats exported (JSON, CSS, SCSS)

Developer Setup

  • [ ] Token files added to project
  • [ ] Build pipeline configured
  • [ ] Theme/CSS variables imported
  • [ ] Hot reload working for token changes

Design Sync

  • [ ] Figma/design tool updated with tokens
  • [ ] Component library aligned
  • [ ] Documentation generated
  • [ ] Storybook stories created

Validation

  • [ ] Colors render correctly
  • [ ] Typography scales properly
  • [ ] Spacing matches design
  • [ ] Responsive breakpoints work
  • [ ] Dark mode tokens (if applicable)

Documentation Deliverables

| Document | Contents | |----------|----------| | design-tokens.json | All tokens in JSON | | design-tokens.css | CSS custom properties | | _design-tokens.scss | SCSS variables | | README.md | Usage instructions | | CHANGELOG.md | Token version history |


Version Control

Token Versioning

{
  "meta": {
    "version": "1.2.0",
    "style": "modern",
    "generated": "2024-01-15",
    "changelog": [
      "1.2.0 - Added animation tokens",
      "1.1.0 - Updated primary color",
      "1.0.0 - Initial release"
    ]
  }
}

Breaking Change Policy

| Change Type | Version Bump | Migration | |-------------|--------------|-----------| | Add new token | Patch (1.0.x) | None | | Change token value | Minor (1.x.0) | Optional | | Rename/remove token | Major (x.0.0) | Required |


See also: token-generation.md for generation options