Guideline 07Evolving

Assets and distribution

Reusable tokens, package exports, presets, icon policy, media requirements, and the source-of-truth map for every consumer.

Owner: Design Systems and Frontend Platform
Last reviewed: August 2026
Review cadence: Every package and token release
Source of truth: Repository package exports and generated token artifact

Required outcomes

Consumers can install or download the system without copying values by hand.

Every asset type names its canonical source and update path.

Generated exports fail validation when they drift from source CSS.

Reusable downloads

The downloadable token artifact is generated from canonical CSS. Code consumers use package exports directly.

Asset directory

Design tokens JSON

Generated DTCG-shaped token data with reference, semantic, layout, radius, motion, and light/dark mode values.

Download JSON

Design-system manifest

Versioned machine-readable contract for every public export, component, guideline, source, token dependency, and blocking validation command.

Download JSON

AI agent quick context

Concise operating rules and links for tools that discover llms.txt.

Open text

AI agent full context

Complete readable component, accessibility, implementation, guideline, template, and validation reference.

Open text

Token CSS

Canonical CSS custom properties for product runtimes.

View source

Tailwind preset

Theme mappings, typography families, radii, semantic colors, and motion utilities.

View source

Approved page templates

Six complete production archetypes with loading, empty, error, permission, and completion states.

View source

Agent integration guide

Query commands, consumer setup, exception policy, CI gates, and MCP adapter guidance.

Read guide

Component package

Public React components, utilities, providers, and motion helpers.

Open repository

Consumer setup

Import tokens once, extend the preset, then import public components from the package root.

tsx

// app/globals.css
@import '@ai-created/ui/styles/tokens.css';

// tailwind.config.js
module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: ['./src/**/*.{ts,tsx}'],
};

// product UI
import { Button, Surface } from '@ai-created/ui';

AI agent contract

Agents use the same versioned inputs and blocking gates as human contributors, without inferring undocumented design decisions.

Agent operating model

Query canonical context

Read the manifest or query CLI before implementation. Never reconstruct props, variants, or tokens from model memory.

Start from an approved archetype

Use the directory, detail, form, settings, dashboard, or onboarding template when its product shape matches.

Reject silent drift

Raw colors, reference tokens, internal imports, arbitrary system values, and local primitive copies fail the policy gate.

Make exceptions accountable

A necessary departure names one rule, narrow files, a concrete reason, an owner, and a future review date.

Agent query and validation

Commands return JSON and validate the same contract that ships with the selected package version.

bash

npm run agent:query -- component button
npm run agent:query -- guideline accessibility
npm run agent:query -- template dashboard
npm run agent:check

Agent entry points

Start at the overview when introducing the model to a team. Stay in this chapter for the canonical rules.

Agents overview

Product-level explanation of how agents query the contract, what validation rejects, and how exceptions reach human review.

Open page

AI agent integration guide

Consumer setup, required gates, repository enforcement, and adapter guidance.

Read guide

Source-of-truth map

Each asset has one canonical authoring location and an explicit distribution path.

Asset ownership

Asset	Canonical source	Distribution	Change gate
Reference and semantic tokens	styles/tokens.css	CSS package export and generated JSON	Theme and contrast review
Tailwind mappings	tailwind-preset.js	Preset package export	Matches canonical CSS names
React components	src/components	Package root exports	API, a11y, unit, interaction and visual review
Component specifications	playground/specs	This portal	Registry completeness and parity tests
Icons	Lucide dependency	lucide-react	Use standard glyph before custom asset
Product imagery	Owning product repository	Product deployment	Theme, crop, rights and accessibility review
Visual baselines	e2e/__screenshots__	Repository test artifact	Intentional reviewed update
Agent manifest and context	Runtime, tokens, registries, templates, and AGENTS.md	Package files and portal downloads	Generated parity and freshness checks

Design library model

A future design-tool library should mirror this portal without becoming a competing source of truth.

Recommended library pages

Page	Contents
00 Cover and release	Version, status, owner, release notes, migration alerts
01 Foundations	Variables, text styles, layout, radius, motion, icon and media rules
02 Components	Published component sets matching public exports
03 Patterns	Approved compositions and complete state flows
04 Accessibility	Annotations, focus order, keyboard and announcement notes
05 QA	Theme, locale, resize, density and exceptional-state comparison frames
99 Deprecated	Migration-only assets with removal version

Publishing policy

Version the release

Publish design assets with the corresponding package version and changelog.

Expose semantic variables

Consumers select intent. Reference values remain hidden from product authoring.

Keep code-only exports honest

Providers and utilities receive documentation, not artificial canvas components.

Audit detached instances

Detachment signals either missing capability or unsupported product drift.

Asset quality gates

Reusable assets are complete only when their licensing, modes, states, naming, and fallback behavior are documented.

Release checklist by asset type

Tokens

Generated artifact matches CSS.
Aliases resolve without cycles.
Light and dark modes are complete.
Names and types remain stable or include migration.

Icons

Optical size matches 16, 20, or 32px role.
Accessible name comes from the control or nearby text.
Directionality is documented.
Custom icons include source and license.

Media

Usage rights and source are recorded.
Light/dark variants and crops are paired.
Fallback and alt behavior is defined.
Files meet product performance budgets.