05 - Prompted Design System

A Prompted Design System is a modern approach to creating a reusable library of user interface (UI) components and standards, using AI as a primary tool for generation, documentation, and maintenance. This is not about replacing designers or developers, but about empowering them with AI to build more consistent and robust UIs at a much faster pace. By crafting precise prompts, you can direct an AI to generate components that adhere to a predefined visual language, ensuring brand consistency across all your applications. This guide provides a ten-step blueprint for building your own design system from the ground up using this prompt-driven workflow. The ultimate goal is to create a single source of truth for your UI that is both easy to use and simple to maintain.

---

Step 1: Define Your Foundational Design Tokens

The Goal: Before creating any components, you must first define the fundamental "design tokens"—the core visual properties that will govern your entire system.

The Action: This involves making concrete decisions about your color palette, typography (fonts, sizes, weights), and spacing units. These tokens are the "atoms" of your design system. We will prompt an AI to generate a structured format for these tokens that our components can reference.

• 🤖 AI Prompt Example:

  "Generate a theme configuration object in JSON format for my design system. It must include a colors object with keys for primary (a dark blue), secondary (a teal), neutral (a range of grays from 100 to 900), error (a red), and success (a green). Also include a typography object with fontSizes (from 'sm' to 'xl') and fontWeights (regular, medium, bold). Finally, add a spacing object with numeric values based on a 4-pixel grid system."

• Technology Choices & Connections:

Option	Language	When & Why to Choose It	Connects To...
1. CSS Custom Properties	CSS	The Web Standard. Choose this for a framework-agnostic approach. The tokens are defined in a global CSS file and can be used by any component, regardless of the JavaScript framework.	Your root CSS file (:root {}), which then provides global variables to all your Frontend Components.
2. Tailwind CSS Config	JavaScript	The Utility-First Choice. If your project is built with Tailwind, defining your tokens here allows you to use them as utility classes (e.g., bg-primary, text-lg).	The tailwind.config.js file. This directly connects your design decisions to the Tailwind CSS styling engine.
3. Style Dictionary	JSON	The Cross-Platform Choice. Choose this if you need to support multiple platforms (e.g., Web, iOS, Android). It takes a standard JSON file and can export tokens in many different formats.	This is a build tool that connects your central JSON token file to multiple outputs, ensuring consistency across your entire Product Ecosystem.

---

Step 2: Choose Your Development & Documentation Tooling

The Goal: Select the primary "workshop" where you will build, test, view, and document your components in isolation.

The Action: This decision determines your entire workflow. We will choose a tool that allows for isolated component development, which is a core principle of building a design system.

• 🤖 AI Prompt Example:

  "I need to choose a tool to build my React component library. Create a brief comparison table explaining the primary differences between Storybook, Bit, and Framer."

• Technology Choices & Connections:

Option	Language	When & Why to Choose It	Connects To...
1. Storybook	TypeScript/JS	The Industry Standard. Choose this for a robust, dedicated environment for building and documenting components in isolation. It has a massive ecosystem of addons.	It connects to your component codebase, providing an interactive sandbox. The final Storybook site is then deployed to an Infrastructure Platform like Vercel.
2. Bit	TypeScript/JS	For Independent Components. Choose this when you want to treat every component as its own independent, versioned, and publishable package.	Bit has its own cloud hosting for components, connecting your codebase to a powerful Component Registry and CI/CD system.
3. Framer	TypeScript/JS	For Design-Led Systems. Choose this when your primary goal is to create a visually rich, interactive design system website where the design and the component are one and the same.	Framer is its own integrated Design and Infrastructure Platform, connecting your design work directly to a live, hosted URL.

---

Step 3: Generate an Atomic Component (The Button)

The Goal: Start with the smallest, most fundamental building block of any UI: the button.

The Action: We'll write a detailed prompt that instructs the AI to create a button component which uses the design tokens we defined in Step 1.

• 🤖 AI Prompt Example:

  "Generate a reusable React Button component using TypeScript. It must accept a variant prop ('primary' or 'secondary') and a size prop ('sm' or 'md'). Using Tailwind CSS, style the primary variant with the primary color token from our theme config, and the secondary variant with the secondary color. The component should render a standard HTML <button> element."

• Technology Choices & Connections:

Option	Language	When & Why to Choose It	Connects To...
1. Tailwind CSS	CSS	For Rapid Custom Styling.	Connects your React Component to your tailwind.config.js Design Tokens, allowing for fast, utility-based styling.
2. CSS-in-JS	TypeScript/JS	For Encapsulated Styles.	Connects your styles directly to your React Component file, preventing style leakage and making the component a self-contained unit.
3. CSS Modules	CSS	For Scoped, Performant CSS.	Connects a standard CSS file to a single React Component, ensuring class names are unique and don't conflict globally.

---

Step 4: Generate a Composite Component (The Card)

The Goal: Combine our atomic Button component with other elements to create a more complex, composite component.

The Action: We will prompt the AI to build a "Card" component that uses our Button component as a child element. This tests the reusability of our system.

• 🤖 AI Prompt Example:

  "Create a ProductCard React component. It should have a designated slot for an image at the top, a title (h3), a description (p), and at the bottom, it must render the PrimaryButton component we already created, passing the text 'View Details' to it."

• Technology Choices & Connections:

Option	Language	When & Why to Choose It	Connects To...
1. Standard Props	TypeScript/JS	For Simple Composition. Pass components directly as props (e.g., <Card actionButton={<Button />} />).	Connects a parent component to a child by treating the child as a piece of data.
2. React children	TypeScript/JS	The Standard React Pattern. The most common and flexible way to compose components in React (e.g., <Card><Button/></Card>).	Connects components by allowing you to nest them in a natural, HTML-like way.
3. Compound Components	TypeScript/JS	For Tightly Coupled Sets. For creating a set of components that are designed to work together as a single unit (e.g., <Menu><Menu.Item/></Menu>).	This connects multiple components by having them share an implicit, underlying state managed by the parent.

---

Step 5: Generate a Data-Input Component (The Form Input)

The Goal: Create a robust and accessible form input component, defining its various visual states.

The Action: Prompt the AI to generate an Input component that handles states like focus, error, and disabled.

• 🤖 AI Prompt Example:

  "Generate a React Input component that wraps a standard HTML <input>. It must accept a label and an error message prop. Using Tailwind CSS, the border should be gray by default, turn blue on :focus, and turn red if the error prop is present. If the component receives a disabled prop, it should have a light gray background and muted text."

• Technology Choices & Connections:

Option	Language	When & Why to Choose It	Connects To...
1. Uncontrolled Component	HTML/JS	For Simple Forms. The component's state is handled by the browser's DOM itself. Simple and performant.	Connects directly to native HTML form behavior.
2. Controlled Component	TypeScript/JS	For Interactive Forms. The component's value is controlled by React state (useState). This gives you full control and allows for real-time validation.	Connects the component's value directly to your application's Frontend State Management.
3. Form Library Integration	TypeScript/JS	For Complex Forms. Use a library like React Hook Form or Formik to manage state, validation, and submission for large forms.	Connects your component to a powerful, dedicated Form State Management library, abstracting away the complexity.

---

Step 6: Generate Component Documentation

The Goal: Use AI to automatically write clear, helpful documentation for the components we've created.

The Action: Provide the AI with the component's code and ask it to generate user-facing documentation.

• 🤖 AI Prompt Example:

  "Here is the code for my PrimaryButton component: [paste code]. Generate documentation for it in MDX format. The documentation should include a brief description, a list of all available props with their types and default values, and at least two usage examples: one for a primary button and one for a secondary button."

• Technology Choices & Connections:

Option	Language	When & Why to Choose It	Connects To...
1. MDX	MDX	For Interactive Docs. MDX allows you to write JSX (React components) directly inside your Markdown files, creating live, interactive examples.	This connects your documentation directly to your live Component Library, making your docs a living part of your system.
2. JSDoc Comments	JavaScript	For Docs-as-Code. Write documentation directly in code comments. Tools can then parse these comments to automatically generate a documentation site.	This connects your documentation directly to your source code, ensuring that the docs are always located right next to the code they describe.
3. Notion	Markdown	For Easy Collaboration. Use Notion for its familiar writing interface and collaborative features, especially if non-developers need to contribute to docs.	This connects your design system documentation to a widely-used Collaboration Tool, making it accessible to your whole team.

---

Step 7: Implement Accessibility Checks

The Goal: Ensure the components are usable by everyone, including people with disabilities.

The Action: Prompt an AI to analyze our component code and suggest improvements based on accessibility (a11y) best practices.

• 🤖 AI Prompt Example:

  "Analyze the code for my PrimaryButton component: [paste code]. Check it for common accessibility issues. Specifically, ensure it can be operated by a keyboard, has a sufficient color contrast ratio, and includes the necessary ARIA attributes."

• Technology Choices & Connections:

Option	Language	When & Why to Choose It	Connects To...
1. Storybook A11y Addon	N/A	For Live Testing. Provides an accessibility panel directly within Storybook, allowing you to test components for issues as you build them.	Connects the WAVE/Axe accessibility testing engines directly to your Component Development Environment.
2. ESLint JSX A11y Plugin	JavaScript	For Static Analysis. Checks your code for accessibility issues automatically in your code editor as you type.	Connects accessibility rules directly to your Code Editor, providing real-time feedback.
3. Jest Axe	TypeScript/JS	For Automated Testing. Write automated tests that check your components for accessibility violations as part of your CI/CD pipeline.	Connects accessibility testing to your Automated Test Suite, preventing regressions from being deployed.

---

Step 8: Version & Publish the System

The Goal: Package the design system so it can be installed and used in other projects.

The Action: We'll choose a package manager or platform to publish our component library.

• 🤖 AI Prompt Example:

  "Generate the necessary configuration for my package.json file to publish my React component library to the NPM registry. It needs a name, version, main entry point, and peer dependencies for react and react-dom."

• Technology Choices & Connections:

Option	Language	When & Why to Choose It	Connects To...
1. NPM / GitHub Packages	JSON	The Public Standard. The default way to distribute and share JavaScript code with the world or within a private organization.	This connects your design system to the global JavaScript Package Management ecosystem.
2. Bit.dev	N/A	For Independent Components. A cloud platform that allows you to publish, version, and share each component as its own independent package.	This connects your components to a dedicated Component Cloud Hosting platform, making them easily discoverable and shareable.
3. Local Monorepo	N/A	For Internal Sharing. Use a tool like Turborepo or Nx to manage a single repository that contains both your design system and the projects that use it.	This connects your design system directly to your applications within a single Git Repository, simplifying local development.

---

Step 9: Integrate the System into a Project

The Goal: Use our newly published design system in a separate application.

The Action: We'll install our component library package and import the components to build a new UI.

• 🤖 AI Prompt Example:

  "I have published my design system to NPM as @my-org/ui. Show me the command to install it in a new Next.js project. Then, show me how to import the PrimaryButton component and use it on my homepage."

• Technology Choices & Connections:

Option	Language	When & Why to Choose It	Connects To...
1. Next.js App	TypeScript/JS	For a Fullstack App. Demonstrate how a complete web application consumes the design system.	This connects your Design System to a real-world Fullstack Builder, proving its utility.
2. Astro Site	TypeScript/JS	For a Static Site. Show how a content-focused site can use the design system for consistent branding.	This connects your Design System to a different type of Frontend Framework, showcasing its flexibility.
3. Storybook Itself	TypeScript/JS	For Documentation. The design system's own Storybook is the primary consumer of its components for documentation purposes.	This connects your components back to their own Documentation Platform.

---

Step 10: Automate Maintenance & Updates

The Goal: Set up an automated pipeline to test and publish new versions of the design system whenever we make changes.

The Action: We will prompt an AI to generate a CI/CD workflow file.

• 🤖 AI Prompt Example:

  "Generate a GitHub Actions workflow that triggers on every push to the main branch. The workflow must install dependencies, run the linter, run the full test suite (including accessibility tests), and if all checks pass, automatically publish a new version of the package to NPM using an NPM_TOKEN secret."

• Technology Choices & Connections:

Option	Language	When & Why to Choose It	Connects To...
1. GitHub Actions	YAML	For GitHub-Native CI/CD. Tightly integrated with your GitHub repository, making it the easiest choice if your code is hosted there.	This connects your Git Repository directly to the NPM Package Registry, automating your release process.
2. CircleCI	YAML	For Complex Workflows. A powerful and highly configurable CI/CD platform that can handle very complex testing and deployment scenarios.	This connects your Git Repository to a dedicated, high-performance CI/CD Platform.
3. Vercel / Netlify	N/A	For Deploying the Docs. These platforms can be configured to automatically deploy your Storybook documentation site.	This connects your Design System's Documentation to a world-class Infrastructure Platform.

---

Building a design system is a foundational investment that pays massive dividends in consistency and development speed. By using AI as a partner in this process, you can create, document, and maintain a professional-grade system more efficiently than ever before. This approach transforms a once-daunting task into a manageable and creative process. The resulting system becomes the heart of your product's user experience. Ultimately, a well-prompted design system allows you to scale your creative vision without sacrificing quality.