Map Your Design System to Component Models

If your team has a design system (in Figma, Storybook or code), most of your Agility model is already designed. The work is deciding which parts of the design system become Component Models, which become fields, which become Content Models, and which stay in code. This page gives you a mapping and the rules for the decisions that cause the most rework: variants, naming and nesting.

The mapping

A design system is usually described in layers, from tokens up to pages. Here is where each layer lives in Agility.

Design system layer	Example	In Agility	Notes
Tokens	Colours, spacing, type scale	Code (CSS custom properties, theme config)	Editors choose from a few named options, never raw values
Atoms	Button, heading, image, icon	Fields on a Component or Content Model	A button is a URL field plus, if needed, a style choice
Molecules	Card, quote, stat	Fields on a Component, or items in a nested list	A card grid's cards are usually nested items
Organisms (sections)	Hero, card grid, FAQ, pricing table	Component Models	The blocks editors add to pages
Templates	Landing page, article page	Page Models with zones	Zones say where Components can go
Pages	The pricing page	Pages in the sitemap	Built by editors from Components
Reusable content	Authors, testimonials, offices	Content Models and lists	Linked from Components, not typed into them

The organism layer is the one that matters most. A good Component Model is a section an editor would describe in one phrase: "a hero", "a row of logos", "an FAQ". Atoms are too small to be Components, because a page built from loose headings and buttons is hard to edit and impossible to keep on brand.

Each Component Model needs a matching front-end component, registered in your code under the Component Model's reference name, or nothing renders. See Component Models and Component Architecture Strategy.

Variants: a field or a separate Component?

Design systems are full of variants: a hero with the image left or right, a card in light or dark, a compact or full pricing table. Use this rule:

• Same fields, different look: one Component with a variant field. Add a Drop-down List such as Layout with values image-left and image-right. The API returns the selected value, so your code switches on it, and editors see readable labels.
• Different fields: separate Components. If the "video hero" needs a video URL and autoplay settings that the "image hero" doesn't, make two Components. Forcing both into one model leaves editors with fields that do nothing.
• A few fields differ: one Component, with hide/when. If one variant adds a single field, a hide/when formula can show it only when that variant is chosen. If you need more than two or three formulas, split the Component.

Keep the number of variant fields small. Each one doubles the combinations your front end has to render and your designers have to approve.

Tokens: give editors names, not values

Never let editors type hex codes, pixel values or class names. Offer a short list of named choices that map to your tokens:

• A Drop-down List (Background: default, muted, brand) whose values your code maps to CSS custom properties.
• The Picker Fields app, which adds icon pickers for several icon libraries and a named colour picker. Each picker stores a plain text value.

If a token changes in the design system, you change one mapping in code, and no content needs editing.

Naming

Names are the contract between design, code and content:

• Use the design system's names for Component Models, so a designer, a developer and an editor all mean the same thing by "Feature Grid". Put the Figma component name in the Component Model's description if the two differ.
• Choose reference names once. Your code registers components and reads fields by these names, and the APIs return field names with the first letter lowercased (CtaLink becomes ctaLink). Renaming later means changing code and queries. See Content Modeling Anti-Patterns.
• Name fields for meaning, not position. Heading and Summary, not Text1 and TopLeftText.

Repeating items and shared content

• Repeating items inside one section (the cards in a card grid, the questions in an FAQ) belong in a nested list on the Component, using a Nested Grid field.
• Content that appears in many places (testimonials, team members, a legal disclaimer) belongs in a shared content list, linked from the Component. Editors update it once.
• Avoid nesting sections inside sections. If the design shows tabs or accordions that hold other sections, use a marker Component that starts each group, and do the grouping when you render: see Grouping Components into Tabs, Accordions, and Sections.

See Nest, Link or Share? for the full decision.

Templates and zones

Map each page template in the design system to a Page Model. Give it one zone per area where editors place Components, for example a main zone and a sidebar zone. Keep templates few: most marketing sites need a small number of Page Models and a larger library of Components.

Page Model zones can also carry default components, so a new page starts with the Components a template normally has.

Visual editing

If editors will use Web Studio, your front-end components need data-agility-* attributes so editors can click a field on the page and edit it. Plan them as part of each component, not as a later pass. Agility Decorate can add them to Next.js components for you, and Writing an AGENTS.md for Agility Projects lists the rules.

A working method

1. Inventory the sections in your design system and on your key page designs. Merge near-duplicates.
2. Write each section as a Component Model on paper: name, fields, field types, which fields are required, and any variant field.
3. Pull reusable content out into Content Models and lists.
4. Map templates to Page Models and zones.
5. Build one page end to end (model, content, front end) before you build the rest. You'll find the naming and variant problems early, while they're cheap.
6. Keep a mapping table (design component, Component Model reference name, front-end component) in your repository, and update it with every change.

Related

• Component Models
• Page Models
• Content Modeling Anti-Patterns
• Nest, Link or Share? Choosing Linked Content Field Types
• Component Architecture Strategy