Design System Rules

Naming conventions, component categories, Sketch mapping, and maintenance checklists. These rules ensure the Sketch MCP bridge can parse, match, and sync every token, component, and view automatically.

Naming Convention Matrix

Layer	Convention	Example	Rule
Folder names	kebab-case	property-card/, filter-modal/	Always lowercase, hyphens only
File names	kebab-case + suffix	property-card.tsx, property-card.module.css	Match folder name exactly
CSS classes	camelCase	.slideArea, .priceRow, .actionPill	Single word for primitives, camelCase for compound
CSS variables	--{category}-{name}	--color-brand, --space-md	Always kebab-case, always start with category prefix
Token keys	{category}-{name}	color-brand, type-scale-base	Matches CSS variable without -- prefix
Material names	material-{name}	material-card, material-glass	Always prefixed with material-
React components	PascalCase	PropertyCard, FilterModal	Matches folder name in PascalCase
React props	camelCase	supabaseUrl, propertyHref	Standard React convention
View slugs	kebab-case	property-detail, building-detail	Matches folder name in views/
View meta exports	{name}Meta	propertyDetailMeta, homepageMeta	camelCase + Meta suffix
Sketch symbols	{Category} / {Name}	Display / Thumbnail / Property	Title Case, forward-slash separated
Sketch color vars	Colors / {Label}	Colors / Brand, Colors / Text Muted	Matches token label from TOKEN_DEFINITIONS
Sketch text styles	Typography / {Label}	Typography / Heading	Matches font token labels
Sketch layer styles	Materials / {Label}	Materials / Card, Materials / Glass	Matches material label from MATERIALS

Component Categories

Every component belongs to exactly one category. This determines its Sketch symbol prefix and Designer gallery grouping.

Category	Sketch Prefix	Components
Primitives	Primitives /	Button, Input, Select, Badge, Toggle
Layout	Layout /	Stack, Grid, Container, Divider
Display	Display /	Thumbnail, PropertyCard, EntityThumbnail, ThumbnailGrid, PropertyGallery, Skeleton
Navigation	Navigation /	Navbar, SearchTrigger, Tabs, Breadcrumb, Pagination
Overlay	Overlay /	Modal, SearchModal, FilterModal, PickerModal, BuildingFilterModal
Map	Map /	MapView, Marker, MapPropertyPanel, MapControls
Editor	Editor /	EditorLayout, EditorSection, EditorField, ImageSection, DataTable
Blocks	Blocks /	HeroCentered, HeroSplit, TextImage, StatsGrid, Testimonials

Component Naming Rules

Folder → File → Class → Sketch Mapping

Folder:   packages/ui/src/components/property-card/
Files:    property-card.tsx, property-card.module.css, index.ts
Export:   PropertyCard (PascalCase of folder)
CSS root: .root or .card (semantic, matches component purpose)
Sketch:   Display / Property Card

Variant Naming (CSS Module Classes)

/* Base class = component purpose */
.pill { }

/* Active/selected state = base + State */
.pillActive { }

/* Size variants = base + Size */
.pillSm { }
.pillLg { }

/* Context variants = descriptive camelCase */
.aspectProperty { aspect-ratio: 4/3; }
.aspectEntity { aspect-ratio: 3/4; }

Variant Naming (Sketch Symbols)

{Category} / {Component} / {Variant}

Display / Thumbnail / Property      <- default (4/3 aspect)
Display / Thumbnail / Entity        <- 3/4 aspect
Display / Thumbnail / Square        <- 1/1 aspect

Overlay / Modal / With Title
Overlay / Modal / Headerless
Overlay / Modal / Large

Navigation / Search Bar / Default
Navigation / Search Bar / With Filters
Navigation / Search Bar / With Toggle

The Sketch symbol path maps directly to code: Category → component category in Designer gallery, Component → folder name in components/, Variant → variant key in .variants.ts

View Naming Rules

Folder:   packages/ui/src/views/property-detail/
Files:    property-detail.view.tsx, property-detail.module.css, property-detail.meta.ts, index.ts
Export:   PropertyDetailView
Meta:     propertyDetailMeta
Slug:     "property-detail"
Sketch:   Pages / Property Detail / Full Page
          Pages / Property Detail / Full Page Mobile
          Pages / Property Detail / Side Panel

View Variant Naming in Sketch

Pages / {View Name} / {Variant Name}

Pages / Property Detail / Full Page
Pages / Property Detail / Full Page Mobile
Pages / Homepage / Desktop
Pages / Homepage / Mobile
Pages / Building Detail / Full Page

Token Naming Rules

Adding a New Token

Key: {category}-{name} in kebab-case (e.g., color-brand-muted)
CSS var: --{key} (e.g., --color-brand-muted)
Label: Title Case for humans (e.g., "Brand Muted")
Sketch name: Colors / {Label} (e.g., "Colors / Brand Muted")
Add to packages/tokens/src/definitions.ts (TOKEN_DEFINITIONS array)
Add default value to packages/tokens/src/defaults.ts
Run pnpm design:generate to regenerate tokens.css

Adding a New Material

Name: material-{name} in kebab-case
Label: Title Case
Sketch name: Materials / {Label}
Add to packages/tokens/src/materials.ts (MATERIALS array)
Run pnpm design:generate

Maintenance Checklists

When Adding a New Component

Create folder: packages/ui/src/components/{name}/
Create files: {name}.tsx, {name}.module.css, index.ts
Export from packages/ui/src/index.ts
Add to Designer app component list in apps/designer/src/app/components/page.tsx
Create Designer preview page at apps/designer/src/app/components/{name}/page.tsx
Create Sketch symbol: '{Category} / {Name}'
Tag component with app: 'shared' | 'agentos' | 'website' in Designer

When Adding a New View

Create folder: packages/ui/src/views/{name}/
Create files: {name}.view.tsx, {name}.module.css, {name}.meta.ts, index.ts
Add meta to VIEW_REGISTRY in packages/ui/src/views/index.ts
Add fixture data in packages/ui/src/fixtures/ if needed
Create Sketch artboards: 'Pages / {Name} / {Variant}'

When Modifying a Token

Update value in packages/tokens/src/defaults.ts
Run pnpm design:generate
Push to Sketch: use the "Push tokens to Sketch" prompt
Verify in Designer app at /tokens

When Adding a Tenant

Create packages/tokens/src/tenants/{slug}.json with override values only
Add tenant to apps/designer/src/components/designer-context.tsx TENANT_OVERRIDES
Preview in Designer at /tenants
Verify key views render correctly with tenant branding

When Renaming or Moving a Component

Update folder and file names (kebab-case)
Update the re-export shim at the old path
Update Designer component list
Rename Sketch symbol to match new path
Run pnpm build to verify no broken imports