◈ Cowork/2026-04-09Advanced

Implementing Design Systems as Claude Skills: Learning from kintone's AI-Ready Documentation

Learn how to transform your design system into AI-readable Claude Agent Skills, using Cybozu's kintone Design System as a reference. This guide covers the differences between MCP and Skills, SKILL.md design principles, and documentation optimization for AI integration.

claude-code¹²⁹ design-system⁴ skills¹⁰ mcp¹⁸ kintone cowork¹³

✦ Premium Article

Design systems are the foundation that accelerates enterprise product development. Yet the harsh reality most organizations face is this: documentation goes unused.

Your Figma component library is beautifully organized. Storybook aggregates all implementations. But when a new engineer joins, they ask: "Where's the design system?" Old documentation never gets updated. The design system becomes window dressing.

The root cause? Documentation is optimized for humans, not for AI.

But what if you provided your design system in "AI-readable format"? Claude Code and other AI agents could access the latest component information in real-time and automatically generate prototypes. Here's the surprising part: documentation optimized for AI becomes easier for humans too.

This article explores how Cybozu's kintone Design System was transformed into Claude Agent Skills, and shows you how to do the same for your design system. The result: turning it into a "treasure chest that AI can read."

Why AI-Readable Design Systems Matter Now

Traditional Design System Sharing Challenges

The way design systems are shared hasn't fundamentally changed in 20 years:

Design UI components in Figma
Implement components (React / Vue / etc.)
Document in Storybook
Tell the team: "Find it in Storybook"

The critical bottleneck: humans manually search through Storybook every time.

Searching for the right component when starting a new project: 30 minutes
Confusion about multiple versions: "Which is current?"
Design system updates don't automatically propagate to dependent projects
Code reviews repeat the same feedback: "Use the Button component instead"

The Perfect Partnership: AI and Design Systems

When you "teach" an AI agent your design system, everything changes:

【Traditional】
"Create an OK button using Button component"
↓
Developer manually searches Storybook
↓
Copy & paste code
↓
Misses design system updates, uses outdated version
 
【AI-Enabled】
"Create an OK button"
↓
AI automatically accesses latest design system
↓
Infers correct component and Props
↓
Automatically uses new version when design system updates

Zero cognitive load. Developers think "I need a button." AI transparently selects the optimal component and configures it correctly.

The kintone Design System Challenge

Cybozu's kintone product features complex enterprise UI. To maintain consistency, the kintone Design System was created.

But scaling brought challenges:

Sharing design guidelines with external partners became difficult
Determining "can we use an existing component or need new one?" took time
Maintaining documentation across multiple languages was a burden

Solution: Expose the design system as Claude Agent Skills—"APIifying" it through AI-readable documentation and SKILL.md.

MCP vs Skills: Two Approaches Compared

There are two major ways to provide design systems to AI. Your choice dramatically affects implementation complexity and maintainability.

Understanding MCP

MCP (Model Context Protocol) is Anthropic's standard for exposing data sources to AI:

{
  "resources": [
    {
      "uri": "figma://file/abc123",
      "name": "kintone Button Component"
    }
  ],
  "tools": [
    {
      "name": "get_component_props"
    }
  ]
}

MCP is powerful, but comes with trade-offs.

MCP Challenges:

Server Infrastructure Required: Needs constant-running Node.js server
Context Pressure: Large MCP responses consume AI's context window (devastating for smaller models)
Complex Auth: OAuth, API key management needed
Latency: Network round-trip overhead

The Skills Approach

Skills uses a simpler pattern—literally a text file:

# kintone Design System
 
## Resources
 
### Button Component
- **Props**: variant, size, disabled
- **Example**: `<Button variant="primary">OK</Button>`

It's just a SKILL.md file in your repository.

Skills Advantages:

No Server Needed: Just add SKILL.md to your repo
Git-Managed: Version control is automatic
Fast: Pre-loaded files, zero network latency
Simple: No complex authentication
Flexible: Easy to expand with README.md

Decision Framework

Factor	MCP	Skills
Scale	Large systems	Mid-size to focused projects
Update Frequency	Real-time sync needed	Git push sufficient
Team Resources	DevOps available	Engineer-driven
Security Needs	Complex authorization	Repository access control
Setup Time	1-2 weeks	Few hours
Maintenance	Complex	Simple

Verdict: For design systems, choose Skills. Design systems evolve slowly; they don't need real-time synchronization.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Understand why Skills is the right choice over MCP for design systems, and master kintone's SKILL.md design patterns for AI readability

✦Get concrete steps and folder structures for implementing your own design system as Claude Skills, ready to integrate with Claude Code

✦Discover how AI-optimized documentation transforms team efficiency by 24x, while simultaneously becoming more useful for humans

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

SKILL.md Design Principles

How do you design SKILL.md so AI can actually use your design system? Three principles emerge from kintone's implementation.

Principle 1: Hierarchical Structure with Reference Chains

SKILL.md is the entry point. Don't dump all information into one file. Guide users step-by-step to details.

Bad (flat):

# Components
 
## Button Props
- variant: "primary" | "secondary" | ...
- size: "sm" | "md" | ...
... 100 more items

Good (hierarchical):

# Design System
 
## Components
- [Button](./src/components/Button/README.mdx)
- [Form](./src/components/Form/README.mdx)
- [Layout](./src/components/Layout/README.mdx)
 
## Design Tokens
See [Design Tokens Guide](./docs/design-tokens.md)

Each component folder has its own README.mdx with details. This minimizes AI's context usage while preserving access to detailed information.

Principle 2: Auto-Discoverable Metadata

Design SKILL.md so AI can auto-detect version, update date, and maintainers from package.json:

{
  "name": "@kintone/design-system",
  "version": "2.5.3",
  "maintainers": ["Design Team <design@cybozu.co.jp>"]
}

Reference this in SKILL.md:

# kintone Design System
 
> Version: 2.5.3 | Updated: 2026-04-08
> Maintained by: Design Systems Team

Principle 3: Explicit Over Implicit

AI struggles with implied information. Humans assume "it's a button, so it triggers actions," but AI needs explicit instruction.

Bad (vague):

### Button
A reusable button component

Good (explicit):

### Button
 
**Purpose**: Trigger actions, submit forms, navigate
 
**When to use**:
- Form submission
- Confirmation dialogs
 
**When NOT to use**:
- Links → use `<a>` tag
- Toggles → use Toggle component
 
**Props**:
- `variant`: "primary" (one per screen) | "secondary" | "danger" (destructive)
- `size`: "sm" (32px) | "md" (40px, standard) | "lg" (48px, CTA)
- `disabled`: boolean (prevents duplicate submissions)

This lets AI correctly select components.

kintone Design System Skills: Implementation Details

Repository Structure Design

kintone-design-system/
├── SKILL.md                    ← AI entry point
├── README.md                   ← Team/external guide
├── package.json                ← Metadata
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx       ← Implementation
│   │   │   ├── Button.stories.tsx ← Storybook
│   │   │   ├── Button.test.tsx
│   │   │   └── README.mdx       ← AI reads this
│   │   └── Form/
│   ├── tokens/
│   │   ├── colors.json         ← Design tokens
│   │   └── typography.json
│   └── utilities/
├── docs/
│   ├── design-tokens.md
│   ├── accessibility.md
│   └── architecture.md
├── .storybook/
└── storybook-static/

Key: Each component is self-contained (implementation + test + doc). Design tokens are centralized. SKILL.md acts as the map.

Auto-Detecting Versions

SKILL.md can be dynamically generated via CI/CD:

// scripts/generate-skill.js
const pkg = require('./package.json');
 
const skillContent = `# ${pkg.name}
 
Version: ${pkg.version}
Updated: ${new Date().toISOString().split('T')[0]}
 
## Components
...
`;

Whenever package.json updates, SKILL.md regenerates automatically. AI always references the current version.

Storybook Integration

Storybook isn't just a UI browser—it's AI's textbook for learning component usage:

// Button.stories.tsx
export default {
  title: 'Components/Button',
  component: Button,
  parameters: {
    ai: {
      description: 'Primary action button for forms and dialogs',
      usage: 'One per screen. Use for main actions.'
    }
  }
};

AI reads this metadata alongside code.

Steps to Make Your Design System AI-Ready

Step 1: Reorganize Repository Structure

Make sure folders are self-contained:

src/components/
├── Button/
│   ├── Button.tsx
│   ├── Button.test.tsx
│   ├── Button.stories.tsx
│   └── README.mdx  ← AI reads here

Step 2: Create Component-Level READMEs

Each component gets its own documentation:

# Button Component
 
## Overview
Primary action button for forms and dialogs.
 
## When to Use
- Form submission
- Main action in dialogs
 
## When NOT to Use
- Links → use `<a>` or Next.js `<Link>`
- Toggles → use Toggle component
 
## Props
- **variant**: "primary" | "secondary" | "danger"
- **size**: "sm" | "md" | "lg"
- **disabled**: boolean
 
## Example
\`\`\`tsx
<Button variant="primary">Submit</Button>
\`\`\`
 
## Accessibility
- Tab navigable
- Screen reader compatible (aria-label)
- Focus indicator visible

Step 3: Create Your SKILL.md

# My Design System
 
> Version: 1.0.0
> Updated: 2026-04-09
 
## Components
- [Button](./src/components/Button/README.mdx)
- [Form](./src/components/Form/README.mdx)
- [Card](./src/components/Card/README.mdx)
 
## Design Tokens
- [Colors](./src/tokens/colors.json)
- [Typography](./src/tokens/typography.json)
 
## Quick Example
\`\`\`tsx
import { Button, Form } from '@mycompany/design-system';
 
<Form onSubmit={handleSubmit}>
  <Button variant="primary">Submit</Button>
</Form>
\`\`\`

Step 4: Automate Updates

Use GitHub Actions to auto-regenerate SKILL.md:

# .github/workflows/generate-skill.yml
name: Generate SKILL.md
on:
  push:
    paths: ['package.json', 'src/**']
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm run generate-skill
      - run: git add SKILL.md && git commit -m "chore: update SKILL.md"
      - run: git push

Step 5: Deploy and Collect Feedback

Push to GitHub, share with teammates, use in Claude Code. Gather feedback:

Did AI recommend the correct component?
Were README instructions sufficient?
What information was missing?

Iterate over 1-2 weeks.

AI-Optimized Documentation Principles

Eight principles emerge when converting design systems to AI-readable format:

Hierarchy (Deep vs Wide): Guide through layers, not one flat file
Eliminate Ambiguity: "Maybe" becomes explicit conditions
Explicit Metadata: Version, update date, maintainer always visible
Use/Don't Use: When to use? When to avoid?
Rich Examples: 3-5 usage scenarios per component
Accessibility Info: ARIA labels, keyboard support, screen readers included
Cross-References: Link related components
Tokenization: Colors, fonts, spacing defined as JSON

Challenges and Solutions from Real Implementation

Challenge 1: Context vs Quality Trade-off

Problem: Including all READMEs in SKILL.md overwhelms AI's context.

Solution: Hierarchy solves this.

SKILL.md: <1KB (entry point only)
Each README.mdx: 1-2KB (details)
Implementation code: reference only

Challenge 2: Team Alignment

Problem: "AI-readable documentation" is a new concept.

Solution: Show results. "Before: Manual component lookup (1 min) → After: AI auto-generation (10 sec)"—seeing 6x improvement motivates teams.

Challenge 3: Continuous Maintenance

Problem: SKILL.md eventually goes stale while package.json gets updated.

Solution: Automate regeneration via CI/CD (GitHub Actions example above).

Impact: Measuring the Efficiency Gain

Before: Traditional Approach

Task	Time
New project setup → search Storybook	30 min
"Which component?" check with designer	15 min
Review component Props in Storybook	10 min
Copy & paste code	5 min
Post-update impact analysis	1 hour
Total	2 hours

After: AI-Enabled Approach

Task	Time
Claude Code generates boilerplate (auto-references SKILL.md)	2 min
AI auto-selects optimal components	automatic
AI auto-infers Props	automatic
Code auto-generation	3 min
Design system updates auto-recognized	automatic
Total	5 minutes

2 hours → 5 minutes = 24x faster.

Per project: 1 hour 55 min saved × 100 projects = 3,100 hours/year saved (equivalent to 3-4 engineers' annual output).

Bonus: AI-optimized documentation becomes easier for humans too:

Clear "when to use" guidance
Rich examples to copy & modify
Explicit version information
Better component selection

Wrapping up: Design Systems and AI's New Relationship

Design systems are critical for enterprise UX/UI quality. Yet most organizations face the same problem: built but unused.

The reason? Documentation optimizes for humans, not AI.

What if you flipped that?

AI automatically suggests optimal components
New project setup becomes 24x faster
Documentation becomes more useful for humans, not less
Entire team development efficiency skyrockets

The lesson from kintone Design System Skills extends beyond "using AI with design systems"—it's a new documentation paradigm.

Start Today:

Add SKILL.md to your design system
Create README.mdx in each component folder
Test with Claude Code
Measure the speedup

The future of design systems and AI is already here. It's time to participate.

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.