dss

type Accessibility struct {
	// WCAGLevel is the target WCAG conformance level (A, AA, AAA).
	WCAGLevel string `json:"wcagLevel" jsonschema:"enum=A,enum=AA,enum=AAA"`

	// WCAGVersion is the WCAG version (e.g., "2.1", "2.2").
	WCAGVersion string `json:"wcagVersion,omitempty"`

	// ColorContrast defines color contrast requirements.
	ColorContrast *ColorContrastRequirements `json:"colorContrast,omitempty"`

	// Keyboard defines keyboard accessibility requirements.
	Keyboard *KeyboardRequirements `json:"keyboard,omitempty"`

	// ScreenReader defines screen reader support requirements.
	ScreenReader *ScreenReaderRequirements `json:"screenReader,omitempty"`

	// Motion defines motion and animation requirements.
	Motion *MotionRequirements `json:"motion,omitempty"`

	// TouchTarget defines touch target size requirements.
	TouchTarget *TouchTargetRequirements `json:"touchTarget,omitempty"`

	// Guidelines provides additional accessibility guidelines.
	Guidelines []AccessibilityGuideline `json:"guidelines,omitempty"`

	// TestingRequirements describes required accessibility testing.
	TestingRequirements []TestingRequirement `json:"testingRequirements,omitempty"`
}

type AccessibilityGuideline struct {
	// ID is a unique identifier.
	ID string `json:"id"`

	// Title is a short title for the guideline.
	Title string `json:"title"`

	// Description explains the guideline.
	Description string `json:"description"`

	// WCAGCriteria lists related WCAG success criteria.
	WCAGCriteria []string `json:"wcagCriteria,omitempty"`

	// Examples demonstrate the guideline.
	Examples []string `json:"examples,omitempty"`
}

type BorderRadiusToken struct {
	// ID is a unique identifier (e.g., "none", "sm", "md", "lg", "full").
	ID string `json:"id"`

	// Value is the border radius with unit.
	Value string `json:"value"`
}

type BorderWidthToken struct {
	// ID is a unique identifier (e.g., "none", "thin", "thick").
	ID string `json:"id"`

	// Value is the border width with unit.
	Value string `json:"value"`
}

type Breakpoint struct {
	// ID is a unique identifier (e.g., "sm", "md", "lg", "xl").
	ID string `json:"id"`

	// MinWidth is the minimum viewport width for this breakpoint.
	MinWidth string `json:"minWidth"`

	// MaxWidth is the maximum viewport width (optional).
	MaxWidth string `json:"maxWidth,omitempty"`

	// Columns overrides the grid columns at this breakpoint.
	Columns int `json:"columns,omitempty"`
}

type CSSGeneratorOptions struct {
	// Format specifies output format: "tailwind4" (default), "css-vars", "scss"
	Format string

	// Prefix for CSS variable names (e.g., "pm" → "--pm-color-primary")
	Prefix string

	// IncludeComments adds usage descriptions as CSS comments
	IncludeComments bool

	// IncludeDarkMode generates dark mode variants
	IncludeDarkMode bool
}

type ColorContrastRequirements struct {
	// NormalTextRatio is the minimum ratio for normal text.
	NormalTextRatio float64 `json:"normalTextRatio"`

	// LargeTextRatio is the minimum ratio for large text.
	LargeTextRatio float64 `json:"largeTextRatio"`

	// NonTextRatio is the minimum ratio for non-text elements.
	NonTextRatio float64 `json:"nonTextRatio,omitempty"`

	// LargeTextThreshold defines what counts as large text (in pixels).
	LargeTextThreshold int `json:"largeTextThreshold,omitempty"`
}

type ColorToken struct {
	// ID is a unique identifier (e.g., "primary-500", "danger-base").
	ID string `json:"id"`

	// Value is the color value in hex, rgb, rgba, or hsl format.
	Value string `json:"value"`

	// Semantic indicates the color's purpose (primary, secondary, danger, etc.).
	Semantic string `json:"semantic,omitempty"`

	// Usage describes when and how to use this color (LLM optimization).
	Usage string `json:"usage,omitempty"`

	// Contrast provides accessibility contrast information.
	Contrast *Contrast `json:"contrast,omitempty"`

	// LightModeValue is an alternate value for light mode (if different).
	LightModeValue string `json:"lightModeValue,omitempty"`

	// DarkModeValue is an alternate value for dark mode.
	DarkModeValue string `json:"darkModeValue,omitempty"`
}

type Component struct {
	// ID is a unique identifier (e.g., "button", "input", "modal").
	ID string `json:"id"`

	// Name is a display name for the component.
	Name string `json:"name"`

	// Description provides an overview of the component's purpose.
	Description string `json:"description,omitempty"`

	// Category groups related components (e.g., "inputs", "navigation", "feedback").
	Category string `json:"category,omitempty"`

	// Variants define different visual or behavioral versions.
	Variants []Variant `json:"variants,omitempty"`

	// States define interactive states (hover, focus, disabled, etc.).
	States []State `json:"states,omitempty"`

	// Props define configurable properties/attributes.
	Props []Prop `json:"props,omitempty"`

	// Slots define content insertion points for composition.
	Slots []Slot `json:"slots,omitempty"`

	// TokensUsed references foundation token IDs used by this component.
	TokensUsed []string `json:"tokensUsed,omitempty"`

	// Constraints define usage limitations and requirements.
	Constraints *Constraints `json:"constraints,omitempty"`

	// Accessibility defines a11y requirements for this component.
	Accessibility *ComponentA11y `json:"accessibility,omitempty"`

	// LLM provides optimization fields for AI code generation.
	LLM *LLMContext `json:"llm,omitempty"`

	// DocumentationURL links to detailed documentation.
	DocumentationURL string `json:"documentationUrl,omitempty" jsonschema:"format=uri"`

	// FigmaURL links to the Figma component.
	FigmaURL string `json:"figmaUrl,omitempty" jsonschema:"format=uri"`
}

type ComponentA11y struct {
	// Role is the ARIA role for the component.
	Role string `json:"role,omitempty"`

	// RequiredAttributes lists required ARIA attributes.
	RequiredAttributes []string `json:"requiredAttributes,omitempty"`

	// KeyboardSupport describes keyboard interaction requirements.
	KeyboardSupport []KeyboardInteraction `json:"keyboardSupport,omitempty"`

	// ScreenReaderNotes provides guidance for screen reader users.
	ScreenReaderNotes string `json:"screenReaderNotes,omitempty"`

	// FocusManagement describes focus behavior.
	FocusManagement string `json:"focusManagement,omitempty"`
}

type Constraints struct {
	// MinWidth is the minimum recommended width.
	MinWidth string `json:"minWidth,omitempty"`

	// MaxWidth is the maximum recommended width.
	MaxWidth string `json:"maxWidth,omitempty"`

	// MaxChildren limits the number of child elements.
	MaxChildren int `json:"maxChildren,omitempty"`

	// RequiredParent specifies a required parent component.
	RequiredParent string `json:"requiredParent,omitempty"`

	// ForbiddenChildren lists components that cannot be nested inside.
	ForbiddenChildren []string `json:"forbiddenChildren,omitempty"`

	// ResponsiveBehavior describes how the component adapts.
	ResponsiveBehavior string `json:"responsiveBehavior,omitempty"`
}

type Content struct {
	// Voice describes the brand's personality and communication style.
	Voice *VoiceGuidelines `json:"voice,omitempty"`

	// Tone provides guidance on adapting voice to different contexts.
	Tone []ToneGuideline `json:"tone,omitempty"`

	// Terminology defines preferred and avoided terms.
	Terminology *Terminology `json:"terminology,omitempty"`

	// Microcopy provides templates for common UI text.
	Microcopy []MicrocopyGuideline `json:"microcopy,omitempty"`

	// WritingStyle provides general writing guidelines.
	WritingStyle *WritingStyle `json:"writingStyle,omitempty"`
}

type Contrast struct {
	// OnLight is the recommended text color when this color is on a light background.
	OnLight string `json:"onLight,omitempty"`

	// OnDark is the recommended text color when this color is on a dark background.
	OnDark string `json:"onDark,omitempty"`

	// Ratio is the contrast ratio against the primary background.
	Ratio float64 `json:"ratio,omitempty"`

	// WCAGLevel indicates the WCAG compliance level (AA, AAA).
	WCAGLevel string `json:"wcagLevel,omitempty" jsonschema:"enum=AA,enum=AAA"`
}

type ContributionPolicy struct {
	// Description provides an overview of the contribution process.
	Description string `json:"description,omitempty"`

	// Guidelines lists contribution guidelines.
	Guidelines []string `json:"guidelines,omitempty"`

	// Workflow describes the contribution workflow.
	Workflow *ContributionWorkflow `json:"workflow,omitempty"`

	// Templates provides PR/issue templates.
	Templates []ContributionTemplate `json:"templates,omitempty"`

	// CodeOfConductURL links to the code of conduct.
	CodeOfConductURL string `json:"codeOfConductUrl,omitempty" jsonschema:"format=uri"`
}

type ContributionTemplate struct {
	// Type is the template type (pr, issue, rfc).
	Type string `json:"type"`

	// Name is the template name.
	Name string `json:"name"`

	// URL links to the template file.
	URL string `json:"url,omitempty" jsonschema:"format=uri"`
}

type ContributionWorkflow struct {
	// Steps lists the contribution steps.
	Steps []WorkflowStep `json:"steps"`

	// RequiredReviewers lists required reviewer roles.
	RequiredReviewers []string `json:"requiredReviewers,omitempty"`

	// AutomatedChecks lists automated checks that must pass.
	AutomatedChecks []string `json:"automatedChecks,omitempty"`
}

type DecisionProcess struct {
	// Description provides an overview of the decision process.
	Description string `json:"description,omitempty"`

	// RFCRequired indicates whether RFCs are required for changes.
	RFCRequired bool `json:"rfcRequired,omitempty"`

	// ApprovalRequired lists who must approve changes.
	ApprovalRequired []string `json:"approvalRequired,omitempty"`

	// DecisionRecordLocation is where decisions are documented.
	DecisionRecordLocation string `json:"decisionRecordLocation,omitempty"`
}

type DeprecatedItem struct {
	// Type is the item type (component, token, pattern).
	Type string `json:"type"`

	// ID is the item identifier.
	ID string `json:"id"`

	// DeprecatedSince is when the item was deprecated.
	DeprecatedSince string `json:"deprecatedSince"`

	// RemovalDate is when the item will be removed.
	RemovalDate string `json:"removalDate,omitempty"`

	// Replacement is the ID of the replacement item.
	Replacement string `json:"replacement,omitempty"`

	// MigrationGuideURL links to migration documentation.
	MigrationGuideURL string `json:"migrationGuideUrl,omitempty" jsonschema:"format=uri"`

	// Reason explains why the item was deprecated.
	Reason string `json:"reason,omitempty"`
}

type DeprecationPolicy struct {
	// WarningPeriod is the minimum time items remain deprecated before removal.
	WarningPeriod string `json:"warningPeriod"`

	// NotificationChannels lists how deprecations are communicated.
	NotificationChannels []string `json:"notificationChannels,omitempty"`

	// MigrationGuideRequired indicates whether migration guides are required.
	MigrationGuideRequired bool `json:"migrationGuideRequired,omitempty"`

	// DeprecatedItems lists currently deprecated items.
	DeprecatedItems []DeprecatedItem `json:"deprecatedItems,omitempty"`
}

type DesignSystem struct {
	// Meta contains system-level metadata.
	Meta Meta `json:"meta"`

	// Principles defines design philosophy and brand values.
	Principles []Principle `json:"principles,omitempty"`

	// Foundations contains design tokens (colors, typography, spacing, etc.).
	Foundations Foundations `json:"foundations"`

	// Components defines reusable UI elements.
	Components []Component `json:"components,omitempty"`

	// Patterns defines multi-component UX solutions.
	Patterns []Pattern `json:"patterns,omitempty"`

	// Templates defines page-level layouts.
	Templates []Template `json:"templates,omitempty"`

	// Content defines voice, tone, and content guidelines.
	Content *Content `json:"content,omitempty"`

	// Accessibility defines system-wide accessibility requirements.
	Accessibility *Accessibility `json:"accessibility,omitempty"`

	// Governance defines versioning, contribution, and deprecation policies.
	Governance *Governance `json:"governance,omitempty"`
}

type DurationToken struct {
	// ID is a unique identifier (e.g., "fast", "normal", "slow").
	ID string `json:"id"`

	// Value is the duration in milliseconds or CSS format.
	Value string `json:"value"`

	// Usage describes when to use this duration.
	Usage string `json:"usage,omitempty"`
}

type EasingToken struct {
	// ID is a unique identifier (e.g., "easeIn", "easeOut", "spring").
	ID string `json:"id"`

	// Value is the CSS timing function or cubic-bezier value.
	Value string `json:"value"`

	// Usage describes when to use this easing.
	Usage string `json:"usage,omitempty"`
}

type ElevationToken struct {
	// ID is a unique identifier (e.g., "sm", "md", "lg", "xl").
	ID string `json:"id"`

	// Value is the CSS box-shadow value.
	Value string `json:"value"`

	// Usage describes when to use this elevation level.
	Usage string `json:"usage,omitempty"`
}

type FontFamily struct {
	// ID is a unique identifier (e.g., "sans", "serif", "mono").
	ID string `json:"id"`

	// Name is a display name for the font family.
	Name string `json:"name"`

	// Stack is the CSS font-family fallback stack (e.g., "'Inter', system-ui, sans-serif").
	// This is the preferred field for font family values.
	Stack string `json:"stack,omitempty"`

	// Value is an alias for Stack (deprecated, use Stack instead).
	Value string `json:"value,omitempty"`

	// Weights lists available font weights (e.g., [400, 500, 600, 700]).
	Weights []int `json:"weights,omitempty"`

	// Source is the URL to load the font (e.g., Google Fonts URL).
	Source string `json:"source,omitempty"`

	// Usage describes when to use this font family.
	Usage string `json:"usage,omitempty"`
}

type FontSize struct {
	// ID is a unique identifier (e.g., "xs", "sm", "base", "lg").
	ID string `json:"id"`

	// Value is the size value with unit (e.g., "1rem", "16px").
	Value string `json:"value"`

	// PixelValue is the equivalent pixel value for reference.
	PixelValue int `json:"pixelValue,omitempty"`
}

type FontWeight struct {
	// ID is a unique identifier (e.g., "normal", "medium", "bold").
	ID string `json:"id"`

	// Value is the numeric weight (100-900).
	Value int `json:"value" jsonschema:"minimum=100,maximum=900"`
}

type Foundations struct {
	// Colors defines the color palette and semantic color tokens.
	Colors []ColorToken `json:"colors,omitempty"`

	// Typography defines font families, sizes, weights, and type scale.
	Typography *Typography `json:"typography,omitempty"`

	// Spacing defines the spacing scale for margins, padding, and gaps.
	Spacing *SpacingScale `json:"spacing,omitempty"`

	// Elevation defines shadow/depth tokens for layering.
	Elevation []ElevationToken `json:"elevation,omitempty"`

	// Motion defines animation and transition tokens.
	Motion *MotionSystem `json:"motion,omitempty"`

	// Grid defines the layout grid system.
	Grid *GridSystem `json:"grid,omitempty"`

	// Breakpoints defines responsive breakpoints.
	Breakpoints []Breakpoint `json:"breakpoints,omitempty"`

	// BorderRadius defines corner radius tokens.
	BorderRadius []BorderRadiusToken `json:"borderRadius,omitempty"`

	// BorderWidth defines border width tokens.
	BorderWidth []BorderWidthToken `json:"borderWidth,omitempty"`

	// Opacity defines opacity scale tokens.
	Opacity []OpacityToken `json:"opacity,omitempty"`

	// ZIndex defines z-index layer tokens.
	ZIndex []ZIndexToken `json:"zIndex,omitempty"`
}

type Governance struct {
	// Versioning describes the versioning strategy.
	Versioning *VersioningPolicy `json:"versioning,omitempty"`

	// Contribution describes how to contribute to the design system.
	Contribution *ContributionPolicy `json:"contribution,omitempty"`

	// Deprecation describes how items are deprecated and removed.
	Deprecation *DeprecationPolicy `json:"deprecation,omitempty"`

	// DecisionProcess describes how design decisions are made.
	DecisionProcess *DecisionProcess `json:"decisionProcess,omitempty"`

	// Ownership describes who owns different parts of the system.
	Ownership []OwnershipRecord `json:"ownership,omitempty"`

	// SupportPolicy describes support commitments.
	SupportPolicy *SupportPolicy `json:"supportPolicy,omitempty"`
}

type GridSystem struct {
	// Columns is the number of columns (e.g., 12).
	Columns int `json:"columns"`

	// GutterWidth is the space between columns.
	GutterWidth string `json:"gutterWidth"`

	// MarginWidth is the outer margin.
	MarginWidth string `json:"marginWidth"`

	// MaxWidth is the maximum container width.
	MaxWidth string `json:"maxWidth,omitempty"`
}

type KeyboardInteraction struct {
	// Key is the key or key combination.
	Key string `json:"key"`

	// Action describes what happens when pressed.
	Action string `json:"action"`
}

type KeyboardRequirements struct {
	// FocusVisible requires visible focus indicators.
	FocusVisible bool `json:"focusVisible"`

	// FocusOrder requires logical focus order.
	FocusOrder bool `json:"focusOrder"`

	// NoKeyboardTrap prevents keyboard traps.
	NoKeyboardTrap bool `json:"noKeyboardTrap"`

	// SkipLinks requires skip navigation links.
	SkipLinks bool `json:"skipLinks,omitempty"`

	// FocusIndicatorMinSize minimum size for focus indicators (in CSS pixels).
	FocusIndicatorMinSize int `json:"focusIndicatorMinSize,omitempty"`

	// ShortcutConflicts lists keyboard shortcuts to avoid.
	ShortcutConflicts []string `json:"shortcutConflicts,omitempty"`
}

type LLMContext struct {
	// Intent describes the primary purpose of this element.
	// Example: "Primary action button for form submissions and important CTAs"
	Intent string `json:"intent,omitempty"`

	// AllowedContexts lists situations where this element should be used.
	// Example: ["form-submit", "modal-confirm", "primary-cta"]
	AllowedContexts []string `json:"allowedContexts,omitempty"`

	// ForbiddenContexts lists situations where this element should NOT be used.
	// Example: ["destructive-action", "navigation", "inline-text"]
	ForbiddenContexts []string `json:"forbiddenContexts,omitempty"`

	// Dependencies lists other elements this one requires.
	// Example: ["form", "icon-library"]
	Dependencies []string `json:"dependencies,omitempty"`

	// ExampleUsage provides code snippets or descriptions of correct usage.
	// Example: ["<Button variant='primary'>Submit</Button>"]
	ExampleUsage []string `json:"exampleUsage,omitempty"`

	// AntiPatterns describes common mistakes to avoid.
	// Example: ["Don't use for destructive actions", "Avoid multiple primary buttons"]
	AntiPatterns []string `json:"antiPatterns,omitempty"`

	// SemanticMeaning describes the user-facing meaning of this element.
	// Example: "Signals the main action users should take"
	SemanticMeaning string `json:"semanticMeaning,omitempty"`

	// RelatedElements lists related elements for context.
	// Example: ["button-secondary", "button-outline", "link"]
	RelatedElements []string `json:"relatedElements,omitempty"`

	// PriorityScore indicates relative importance (1-100).
	// Higher scores mean this element should be preferred when multiple options exist.
	PriorityScore int `json:"priorityScore,omitempty" jsonschema:"minimum=1,maximum=100"`

	// Tags are freeform labels for categorization and search.
	Tags []string `json:"tags,omitempty"`
}

type LLMPromptOptions struct {
	// Format: "markdown" (default), "xml", "json"
	Format string

	// IncludeFoundations includes color/spacing/typography guidance
	IncludeFoundations bool

	// IncludeComponents includes component usage guidelines
	IncludeComponents bool

	// IncludePatterns includes pattern recommendations
	IncludePatterns bool

	// IncludeAccessibility includes a11y requirements
	IncludeAccessibility bool

	// IncludeAntiPatterns emphasizes what NOT to do
	IncludeAntiPatterns bool

	// MaxExamples limits code examples per component (0 = all)
	MaxExamples int
}

type LetterSpacing struct {
	// ID is a unique identifier.
	ID string `json:"id"`

	// Value is the letter spacing value (e.g., "-0.02em", "0.05em").
	Value string `json:"value"`
}

type LineHeight struct {
	// ID is a unique identifier (e.g., "tight", "normal", "relaxed").
	ID string `json:"id"`

	// Value is the line height value (unitless or with unit).
	Value string `json:"value"`
}

type Maintainer struct {
	// Name of the maintainer or team.
	Name string `json:"name"`

	// Email contact for the maintainer.
	Email string `json:"email,omitempty" jsonschema:"format=email"`

	// URL to the maintainer's profile or team page.
	URL string `json:"url,omitempty" jsonschema:"format=uri"`
}

type Meta struct {
	// Name is the design system name (e.g., "Material Design", "Carbon").
	Name string `json:"name"`

	// Version follows semantic versioning (e.g., "1.0.0").
	Version string `json:"version"`

	// Description provides a brief overview of the design system.
	Description string `json:"description,omitempty"`

	// MaturityLevel indicates system maturity (1=experimental, 5=stable).
	MaturityLevel int `json:"maturityLevel,omitempty" jsonschema:"minimum=1,maximum=5"`

	// Repository is the URL to the source repository.
	Repository string `json:"repository,omitempty" jsonschema:"format=uri"`

	// Documentation is the URL to the documentation site.
	Documentation string `json:"documentation,omitempty" jsonschema:"format=uri"`

	// Maintainers lists the people or teams responsible for the system.
	Maintainers []Maintainer `json:"maintainers,omitempty"`

	// License specifies the license under which the system is distributed.
	License string `json:"license,omitempty"`
}

type MicrocopyGuideline struct {
	// ID is a unique identifier.
	ID string `json:"id"`

	// Context describes when this microcopy applies.
	Context string `json:"context"`

	// Template is the text template (may include placeholders).
	Template string `json:"template"`

	// Variables lists placeholder variables in the template.
	Variables []MicrocopyVariable `json:"variables,omitempty"`

	// Examples show the template filled in.
	Examples []string `json:"examples,omitempty"`

	// Notes provides additional guidance.
	Notes string `json:"notes,omitempty"`
}

type MicrocopyVariable struct {
	// Name is the variable name.
	Name string `json:"name"`

	// Description explains what value to use.
	Description string `json:"description"`

	// Examples show sample values.
	Examples []string `json:"examples,omitempty"`
}

type MotionRequirements struct {
	// ReducedMotion requires respecting prefers-reduced-motion.
	ReducedMotion bool `json:"reducedMotion"`

	// NoAutoPlay prevents auto-playing animations longer than 5 seconds.
	NoAutoPlay bool `json:"noAutoPlay,omitempty"`

	// PauseControl requires pause/stop controls for animations.
	PauseControl bool `json:"pauseControl,omitempty"`

	// FlashingThreshold maximum flashes per second (must be <=3).
	FlashingThreshold int `json:"flashingThreshold,omitempty" jsonschema:"maximum=3"`
}

type MotionSystem struct {
	// Durations defines timing duration tokens.
	Durations []DurationToken `json:"durations"`

	// Easings defines easing function tokens.
	Easings []EasingToken `json:"easings"`
}

type OpacityToken struct {
	// ID is a unique identifier (e.g., "0", "50", "100").
	ID string `json:"id"`

	// Value is the opacity value (0-1 or percentage).
	Value string `json:"value"`
}

type OwnershipRecord struct {
	// Area is the area owned (e.g., "foundations", "components/forms").
	Area string `json:"area"`

	// Team is the owning team.
	Team string `json:"team"`

	// ContactEmail is the contact email for the team.
	ContactEmail string `json:"contactEmail,omitempty" jsonschema:"format=email"`

	// SlackChannel is the team's Slack channel.
	SlackChannel string `json:"slackChannel,omitempty"`
}

type Pattern struct {
	// ID is a unique identifier (e.g., "form-validation", "data-table", "modal-flow").
	ID string `json:"id"`

	// Name is a display name for the pattern.
	Name string `json:"name"`

	// Description explains the pattern's purpose and when to use it.
	Description string `json:"description"`

	// Category groups related patterns (e.g., "forms", "navigation", "data-display").
	Category string `json:"category,omitempty"`

	// Components lists the component IDs that make up this pattern.
	Components []PatternComponent `json:"components"`

	// Layout describes how components are arranged.
	Layout *PatternLayout `json:"layout,omitempty"`

	// Behavior describes the interaction flow.
	Behavior string `json:"behavior,omitempty"`

	// Variations lists different configurations of the pattern.
	Variations []PatternVariation `json:"variations,omitempty"`

	// Accessibility defines a11y requirements for the pattern.
	Accessibility *PatternA11y `json:"accessibility,omitempty"`

	// LLM provides optimization fields for AI code generation.
	LLM *LLMContext `json:"llm,omitempty"`

	// DocumentationURL links to detailed documentation.
	DocumentationURL string `json:"documentationUrl,omitempty" jsonschema:"format=uri"`
}

type PatternA11y struct {
	// LandmarkRole is the ARIA landmark for the pattern region.
	LandmarkRole string `json:"landmarkRole,omitempty"`

	// FocusOrder describes the expected tab order.
	FocusOrder []string `json:"focusOrder,omitempty"`

	// LiveRegions lists components that should announce changes.
	LiveRegions []string `json:"liveRegions,omitempty"`

	// Notes provides additional accessibility guidance.
	Notes string `json:"notes,omitempty"`
}

type PatternComponent struct {
	// ComponentID references a component from the components list.
	ComponentID string `json:"componentId"`

	// Role describes the component's role in this pattern.
	Role string `json:"role,omitempty"`

	// Required indicates whether this component is essential.
	Required bool `json:"required,omitempty"`

	// Quantity specifies how many instances (e.g., "1", "1+", "0-1").
	Quantity string `json:"quantity,omitempty"`

	// Configuration provides default props for this usage.
	Configuration map[string]interface{} `json:"configuration,omitempty"`
}

type PatternLayout struct {
	// Type is the layout strategy (flex, grid, stack, etc.).
	Type string `json:"type"`

	// Direction is the primary axis (row, column).
	Direction string `json:"direction,omitempty"`

	// Alignment describes cross-axis alignment.
	Alignment string `json:"alignment,omitempty"`

	// Spacing references a spacing token for gaps.
	Spacing string `json:"spacing,omitempty"`

	// Responsive describes breakpoint-specific changes.
	Responsive []ResponsiveLayout `json:"responsive,omitempty"`
}

type PatternVariation struct {
	// ID is a unique identifier for the variation.
	ID string `json:"id"`

	// Name is a display name.
	Name string `json:"name"`

	// Description explains when to use this variation.
	Description string `json:"description,omitempty"`

	// ComponentChanges lists component differences from the base pattern.
	ComponentChanges []PatternComponent `json:"componentChanges,omitempty"`

	// LayoutChanges describes layout differences.
	LayoutChanges *PatternLayout `json:"layoutChanges,omitempty"`
}

type Principle struct {
	// ID is a unique identifier for the principle.
	ID string `json:"id"`

	// Name is a short, memorable title for the principle.
	Name string `json:"name"`

	// Description explains the principle in detail.
	Description string `json:"description"`

	// Rationale explains why this principle matters.
	Rationale string `json:"rationale,omitempty"`

	// Examples demonstrate the principle in practice.
	Examples []PrincipleExample `json:"examples,omitempty"`

	// Order determines display ordering (lower = first).
	Order int `json:"order,omitempty"`
}

type PrincipleExample struct {
	// Title summarizes the example.
	Title string `json:"title"`

	// Description provides detail about how the principle applies.
	Description string `json:"description"`

	// ImageURL points to a visual demonstration.
	ImageURL string `json:"imageUrl,omitempty" jsonschema:"format=uri"`

	// Good indicates whether this is a positive or negative example.
	Good bool `json:"good"`
}

type Prop struct {
	// Name is the prop name as used in code.
	Name string `json:"name"`

	// Type is the data type (string, number, boolean, enum, etc.).
	Type string `json:"type"`

	// Description explains what the prop controls.
	Description string `json:"description,omitempty"`

	// Required indicates whether the prop must be provided.
	Required bool `json:"required,omitempty"`

	// Default is the default value if not specified.
	Default interface{} `json:"default,omitempty"`

	// EnumValues lists allowed values for enum types.
	EnumValues []string `json:"enumValues,omitempty"`
}

type ReactGeneratorOptions struct {
	// IncludeJSDoc adds JSDoc comments from descriptions
	IncludeJSDoc bool

	// ExportStyle: "named" (export interface), "default" (export default)
	ExportStyle string

	// IncludeVariantUnions generates union types for variants
	IncludeVariantUnions bool

	// BasePropsInterface name to extend (e.g., "HTMLAttributes<HTMLButtonElement>")
	BasePropsInterface string
}

type ResponsiveLayout struct {
	// Breakpoint references a breakpoint ID.
	Breakpoint string `json:"breakpoint"`

	// Changes describes what changes at this breakpoint.
	Changes map[string]string `json:"changes"`
}

type ResponsiveTemplate struct {
	// Breakpoint references a breakpoint ID.
	Breakpoint string `json:"breakpoint"`

	// GridChanges describes grid changes at this breakpoint.
	GridChanges *TemplateGrid `json:"gridChanges,omitempty"`

	// HiddenRegions lists region IDs to hide at this breakpoint.
	HiddenRegions []string `json:"hiddenRegions,omitempty"`

	// RegionChanges lists region modifications at this breakpoint.
	RegionChanges []TemplateRegionChange `json:"regionChanges,omitempty"`
}

type ScreenReaderRequirements struct {
	// SemanticHTML requires semantic HTML elements.
	SemanticHTML bool `json:"semanticHtml"`

	// ARIALabels requires ARIA labels for interactive elements.
	ARIALabels bool `json:"ariaLabels"`

	// LiveRegions requires live regions for dynamic content.
	LiveRegions bool `json:"liveRegions,omitempty"`

	// HeadingStructure requires proper heading hierarchy.
	HeadingStructure bool `json:"headingStructure,omitempty"`

	// SupportedReaders lists screen readers to test with.
	SupportedReaders []string `json:"supportedReaders,omitempty"`
}

type Slot struct {
	// Name is the slot name.
	Name string `json:"name"`

	// Description explains what content belongs in this slot.
	Description string `json:"description,omitempty"`

	// Required indicates whether content must be provided.
	Required bool `json:"required,omitempty"`

	// AllowedComponents lists component IDs that can be inserted.
	AllowedComponents []string `json:"allowedComponents,omitempty"`
}

type SpacingScale struct {
	// BaseUnit is the fundamental spacing unit (e.g., "4px", "0.25rem").
	BaseUnit string `json:"baseUnit"`

	// Scale defines the spacing tokens.
	Scale []SpacingToken `json:"scale"`
}

type SpacingToken struct {
	// ID is a unique identifier (e.g., "0", "1", "2", "4", "8").
	ID string `json:"id"`

	// Value is the spacing value with unit.
	Value string `json:"value"`

	// PixelValue is the equivalent pixel value for reference.
	PixelValue int `json:"pixelValue,omitempty"`
}

type State struct {
	// ID is a unique identifier (hover, active, focus, disabled, error, loading).
	ID string `json:"id"`

	// Name is a display name for the state.
	Name string `json:"name,omitempty"`

	// Description explains when this state applies.
	Description string `json:"description,omitempty"`

	// TokenOverrides lists tokens that change in this state.
	TokenOverrides []TokenOverride `json:"tokenOverrides,omitempty"`
}

type SupportPolicy struct {
	// Description provides an overview of support.
	Description string `json:"description,omitempty"`

	// SupportedVersions lists which versions are currently supported.
	SupportedVersions []SupportedVersion `json:"supportedVersions,omitempty"`

	// SupportChannels lists how to get support.
	SupportChannels []string `json:"supportChannels,omitempty"`

	// ResponseTimeTargets describes expected response times.
	ResponseTimeTargets map[string]string `json:"responseTimeTargets,omitempty"`
}

type SupportedVersion struct {
	// Version is the version number.
	Version string `json:"version"`

	// Status is the support status (active, maintenance, end-of-life).
	Status string `json:"status"`

	// EndOfLifeDate is when support ends.
	EndOfLifeDate string `json:"endOfLifeDate,omitempty"`
}

type Template struct {
	// ID is a unique identifier (e.g., "dashboard", "settings", "auth").
	ID string `json:"id"`

	// Name is a display name for the template.
	Name string `json:"name"`

	// Description explains the template's purpose and when to use it.
	Description string `json:"description"`

	// Category groups related templates (e.g., "admin", "marketing", "app").
	Category string `json:"category,omitempty"`

	// Regions defines the major layout regions.
	Regions []TemplateRegion `json:"regions"`

	// Grid describes the overall grid configuration.
	Grid *TemplateGrid `json:"grid,omitempty"`

	// Patterns lists pattern IDs commonly used in this template.
	Patterns []string `json:"patterns,omitempty"`

	// Responsive describes breakpoint-specific adaptations.
	Responsive []ResponsiveTemplate `json:"responsive,omitempty"`

	// LLM provides optimization fields for AI code generation.
	LLM *LLMContext `json:"llm,omitempty"`

	// DocumentationURL links to detailed documentation.
	DocumentationURL string `json:"documentationUrl,omitempty" jsonschema:"format=uri"`

	// PreviewURL links to a visual preview.
	PreviewURL string `json:"previewUrl,omitempty" jsonschema:"format=uri"`
}

type TemplateGrid struct {
	// Areas is the CSS grid-template-areas value.
	Areas string `json:"areas,omitempty"`

	// Columns is the CSS grid-template-columns value.
	Columns string `json:"columns,omitempty"`

	// Rows is the CSS grid-template-rows value.
	Rows string `json:"rows,omitempty"`

	// Gap references a spacing token for grid gaps.
	Gap string `json:"gap,omitempty"`
}

type TemplateRegion struct {
	// ID is a unique identifier for the region.
	ID string `json:"id"`

	// Name is a display name (e.g., "Header", "Sidebar", "Main Content").
	Name string `json:"name"`

	// Role describes the semantic role of this region.
	Role string `json:"role,omitempty"`

	// Required indicates whether this region must be present.
	Required bool `json:"required,omitempty"`

	// GridArea specifies the CSS grid area name.
	GridArea string `json:"gridArea,omitempty"`

	// MinHeight specifies minimum height.
	MinHeight string `json:"minHeight,omitempty"`

	// MaxHeight specifies maximum height.
	MaxHeight string `json:"maxHeight,omitempty"`

	// Sticky indicates whether the region should stick on scroll.
	Sticky bool `json:"sticky,omitempty"`

	// AllowedPatterns lists pattern IDs that can be placed here.
	AllowedPatterns []string `json:"allowedPatterns,omitempty"`

	// AllowedComponents lists component IDs that can be placed here.
	AllowedComponents []string `json:"allowedComponents,omitempty"`
}

type TemplateRegionChange struct {
	// RegionID references the region being changed.
	RegionID string `json:"regionId"`

	// Changes maps property names to new values.
	Changes map[string]string `json:"changes"`
}

type TermDefinition struct {
	// Term is the word or phrase.
	Term string `json:"term"`

	// Definition explains the term.
	Definition string `json:"definition,omitempty"`

	// Usage explains when and how to use (or avoid) the term.
	Usage string `json:"usage,omitempty"`

	// Alternatives lists alternative terms to use instead (for avoided terms).
	Alternatives []string `json:"alternatives,omitempty"`
}

type Terminology struct {
	// PreferredTerms lists terms to use.
	PreferredTerms []TermDefinition `json:"preferredTerms,omitempty"`

	// AvoidedTerms lists terms to avoid.
	AvoidedTerms []TermDefinition `json:"avoidedTerms,omitempty"`

	// Glossary provides definitions for domain-specific terms.
	Glossary []TermDefinition `json:"glossary,omitempty"`
}

type TestingRequirement struct {
	// Type is the testing type (automated, manual, assistive-tech).
	Type string `json:"type"`

	// Tools lists required testing tools.
	Tools []string `json:"tools,omitempty"`

	// Frequency describes how often testing should occur.
	Frequency string `json:"frequency,omitempty"`

	// Coverage describes what should be tested.
	Coverage string `json:"coverage,omitempty"`
}

type TokenOverride struct {
	// TokenID references the token being overridden.
	TokenID string `json:"tokenId"`

	// Value is the override value.
	Value string `json:"value"`
}

type ToneGuideline struct {
	// Context describes the situation (e.g., "error messages", "success states").
	Context string `json:"context"`

	// Description explains how to adapt tone.
	Description string `json:"description"`

	// Attributes lists tone characteristics for this context.
	Attributes []string `json:"attributes,omitempty"`

	// Examples demonstrate appropriate tone.
	Examples []string `json:"examples,omitempty"`
}

type TouchTargetRequirements struct {
	// MinSize is the minimum touch target size (e.g., "44px").
	MinSize string `json:"minSize"`

	// MinSpacing is the minimum spacing between targets.
	MinSpacing string `json:"minSpacing,omitempty"`
}

type TypeStyle struct {
	// ID is a unique identifier (e.g., "h1", "body-lg", "caption").
	ID string `json:"id"`

	// Name is a display name for the style.
	Name string `json:"name"`

	// FontFamily references a FontFamily ID.
	FontFamily string `json:"fontFamily"`

	// FontSize references a FontSize ID.
	FontSize string `json:"fontSize"`

	// FontWeight references a FontWeight ID.
	FontWeight string `json:"fontWeight"`

	// LineHeight references a LineHeight ID.
	LineHeight string `json:"lineHeight"`

	// LetterSpacing references a LetterSpacing ID.
	LetterSpacing string `json:"letterSpacing,omitempty"`

	// Usage describes when to use this type style (LLM optimization).
	Usage string `json:"usage,omitempty"`
}

type Typography struct {
	// FontFamilies lists available font stacks.
	FontFamilies []FontFamily `json:"fontFamilies"`

	// FontSizes defines the font size scale.
	FontSizes []FontSize `json:"fontSizes"`

	// FontWeights defines available font weights.
	FontWeights []FontWeight `json:"fontWeights"`

	// LineHeights defines line height scale.
	LineHeights []LineHeight `json:"lineHeights"`

	// LetterSpacings defines letter spacing scale.
	LetterSpacings []LetterSpacing `json:"letterSpacings,omitempty"`

	// TypeScale defines complete type styles (heading, body, etc.).
	TypeScale []TypeStyle `json:"typeScale,omitempty"`
}

type ValidationError struct {
	Field   string
	Message string
}

type Variant struct {
	// ID is a unique identifier for the variant.
	ID string `json:"id"`

	// Name is a display name (e.g., "Primary", "Secondary", "Outline").
	Name string `json:"name"`

	// Description explains when to use this variant.
	Description string `json:"description,omitempty"`

	// IsDefault indicates this is the default variant.
	IsDefault bool `json:"isDefault,omitempty"`

	// TokenOverrides lists tokens that differ from the base component.
	TokenOverrides []TokenOverride `json:"tokenOverrides,omitempty"`
}

type VersioningPolicy struct {
	// Strategy is the versioning approach (semver, calver, etc.).
	Strategy string `json:"strategy"`

	// Description explains the versioning policy.
	Description string `json:"description,omitempty"`

	// BreakingChangePolicy explains when breaking changes are allowed.
	BreakingChangePolicy string `json:"breakingChangePolicy,omitempty"`

	// ReleaseSchedule describes the release cadence.
	ReleaseSchedule string `json:"releaseSchedule,omitempty"`

	// ChangelogLocation is the URL or path to the changelog.
	ChangelogLocation string `json:"changelogLocation,omitempty"`
}

type VoiceAttribute struct {
	// Name is the attribute name (e.g., "Friendly", "Professional").
	Name string `json:"name"`

	// Description explains the attribute.
	Description string `json:"description"`

	// DoExamples show correct usage.
	DoExamples []string `json:"doExamples,omitempty"`

	// DontExamples show incorrect usage.
	DontExamples []string `json:"dontExamples,omitempty"`
}

type VoiceExample struct {
	// Context describes when this example applies.
	Context string `json:"context"`

	// Example is the sample text.
	Example string `json:"example"`
}

type VoiceGuidelines struct {
	// Description provides an overview of the voice.
	Description string `json:"description"`

	// Attributes lists key voice characteristics.
	Attributes []VoiceAttribute `json:"attributes"`

	// Examples demonstrate the voice in action.
	Examples []VoiceExample `json:"examples,omitempty"`
}

type WithLLMContext interface {
	// GetLLMContext returns the LLM context for this element.
	GetLLMContext() *LLMContext
}

type WorkflowStep struct {
	// Order is the step number.
	Order int `json:"order"`

	// Name is the step name.
	Name string `json:"name"`

	// Description explains what happens in this step.
	Description string `json:"description"`

	// Assignee describes who is responsible for this step.
	Assignee string `json:"assignee,omitempty"`
}

type WritingStyle struct {
	// Capitalization describes capitalization rules.
	Capitalization string `json:"capitalization,omitempty"`

	// Punctuation describes punctuation guidelines.
	Punctuation string `json:"punctuation,omitempty"`

	// Contractions indicates whether contractions are allowed.
	Contractions string `json:"contractions,omitempty"`

	// Numbers describes how to format numbers.
	Numbers string `json:"numbers,omitempty"`

	// DateTimeFormat describes date/time formatting.
	DateTimeFormat string `json:"dateTimeFormat,omitempty"`

	// ActiveVoice indicates preference for active voice.
	ActiveVoice bool `json:"activeVoice,omitempty"`

	// MaxSentenceLength is the recommended max sentence length.
	MaxSentenceLength int `json:"maxSentenceLength,omitempty"`
}

type ZIndexToken struct {
	// ID is a unique identifier (e.g., "base", "dropdown", "modal", "toast").
	ID string `json:"id"`

	// Value is the z-index number.
	Value int `json:"value"`

	// Usage describes when to use this layer.
	Usage string `json:"usage,omitempty"`
}