dss

type APIStyleValidator struct {
	// Tool is the validator tool identifier.
	// Examples: "spectral", "vacuum", "redocly"
	Tool string `json:"tool"`

	// Type specifies how to invoke the tool.
	Type ValidatorType `json:"type"`

	// Command is the command or path to run.
	Command string `json:"command,omitempty"`

	// Ruleset is the path or URL to the style guide ruleset.
	// For Spectral: path to .spectral.yaml or ruleset URL
	// For api-style-spec: path to style-spec.yaml
	Ruleset string `json:"ruleset,omitempty"`

	// Rules specifies which rules to enable/disable.
	// Tool-specific configuration.
	Rules map[string]RuleSeverity `json:"rules,omitempty"`

	// Required indicates whether validation must pass for compliance.
	Required bool `json:"required,omitempty"`
}

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 AccessibilityRequirements struct {
	ComponentID string `json:"componentId"`
	Component   string `json:"component"`

	// RequiredProps lists props that must be set for accessibility.
	RequiredProps []RequiredProp `json:"requiredProps,omitempty"`

	// Keyboard describes keyboard interaction requirements.
	Keyboard *KeyboardReqs `json:"keyboard,omitempty"`

	// Focus describes focus management requirements.
	Focus *FocusReqs `json:"focus,omitempty"`

	// ColorContrast describes contrast requirements.
	ColorContrast *ContrastReqs `json:"colorContrast,omitempty"`

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

	// Role is the ARIA role for this component.
	Role string `json:"role,omitempty"`

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

type AccessibilityValidator struct {
	// Tool is the validator tool identifier.
	// Examples: "agent-a11y", "axe-core", "pa11y", "lighthouse"
	Tool string `json:"tool"`

	// Type specifies how to invoke the tool.
	Type ValidatorType `json:"type"`

	// Command is the command or path to run (for mcp/cli types).
	// For MCP: the server command (e.g., "agent-a11y mcp serve")
	// For CLI: the executable (e.g., "npx axe")
	Command string `json:"command,omitempty"`

	// Standards lists which accessibility standards to validate.
	// If empty, inherits from Accessibility.WCAGLevel and WCAGVersion.
	// Examples: ["WCAG2.1-AA", "WCAG2.2-AAA", "Section508"]
	Standards []string `json:"standards,omitempty"`

	// Checks specifies which checks to run.
	// Tool-specific; if empty, runs all checks.
	Checks []string `json:"checks,omitempty"`

	// Required indicates whether validation must pass for compliance.
	Required bool `json:"required,omitempty"`
}

type AntiPattern struct {
	ID           string   `json:"id"`
	Description  string   `json:"description"`
	BadExample   string   `json:"badExample"`
	GoodExample  string   `json:"goodExample"`
	WCAGCriteria []string `json:"wcagCriteria,omitempty"`
	Components   []string `json:"components,omitempty"`
}

type AntiPatternsResult struct {
	ComponentID  string        `json:"componentId,omitempty"`
	RuleID       string        `json:"ruleId,omitempty"`
	AntiPatterns []AntiPattern `json:"antiPatterns"`
}

type BindingFormat string

type BindingOptions struct {
	// Format specifies the output format.
	Format BindingFormat

	// SpecDir is the directory containing the design system spec.
	// Used to resolve local component references.
	SpecDir string

	// DefaultStrategy is the fallback strategy when not specified in bindings.
	DefaultStrategy string
}

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 CategoryCertification struct {
	Category string           `json:"category"`
	Status   ComplianceStatus `json:"status"`
	Score    int              `json:"score"`
}

type CategoryCompliance struct {
	// Category name (e.g., "colors", "spacing", "accessibility")
	Category string `json:"category"`

	// Status for this category
	Status ComplianceStatus `json:"status"`

	// Score for this category (0-100)
	Score int `json:"score"`

	// Checked is the number of checks run
	Checked int `json:"checked"`

	// Passed is the number of checks that passed
	Passed int `json:"passed"`

	// Failed is the number of checks that failed
	Failed int `json:"failed"`

	// Blocking indicates if failures in this category block release
	Blocking bool `json:"blocking"`
}

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 ComplianceCertificate struct {
	// ID is a unique certificate identifier
	ID string `json:"id"`

	// Timestamp when certificate was issued
	Timestamp time.Time `json:"timestamp"`

	// ExpiresAt when the certificate expires (optional)
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`

	// DesignSystem the compliance is against
	DesignSystem DesignSystemRef `json:"designSystem"`

	// Target what was certified
	Target ValidationTarget `json:"target"`

	// Status compliance status
	Status ComplianceStatus `json:"status"`

	// Score compliance score
	Score int `json:"score"`

	// Hash cryptographic hash of the report
	Hash string `json:"hash"`

	// Categories summary per category
	Categories []CategoryCertification `json:"categories"`
}

type ComplianceIssue struct {
	// Category this issue belongs to
	Category string `json:"category"`

	// Rule is the rule ID
	Rule string `json:"rule"`

	// Severity is error, warning, or info
	Severity string `json:"severity"`

	// Message describes the issue
	Message string `json:"message"`

	// File is the file path
	File string `json:"file,omitempty"`

	// Line is the line number
	Line int `json:"line,omitempty"`

	// Blocking indicates if this issue blocks release
	Blocking bool `json:"blocking"`

	// Fixable indicates if this can be auto-fixed
	Fixable bool `json:"fixable"`

	// FixSuggestion provides guidance on fixing
	FixSuggestion string `json:"fixSuggestion,omitempty"`
}

type ComplianceOptions struct {
	// IncludeIssues includes detailed issue list in report
	IncludeIssues bool `json:"includeIssues,omitempty"`

	// BlockingCategories lists categories that block release
	// Default: ["colors", "accessibility"]
	BlockingCategories []string `json:"blockingCategories,omitempty"`

	// MinScore is the minimum acceptable score
	MinScore int `json:"minScore,omitempty"`

	// GitInfo includes git commit/branch info if available
	GitInfo bool `json:"gitInfo,omitempty"`
}

type ComplianceReport struct {
	// Timestamp when the report was generated
	Timestamp time.Time `json:"timestamp"`

	// DesignSystem identifies the spec being validated against
	DesignSystem DesignSystemRef `json:"designSystem"`

	// Target describes what was validated
	Target ValidationTarget `json:"target"`

	// Status is the overall compliance status
	Status ComplianceStatus `json:"status"`

	// Score is the overall compliance score (0-100)
	Score int `json:"score"`

	// Categories breaks down compliance by category
	Categories []CategoryCompliance `json:"categories"`

	// Summary provides aggregate statistics
	Summary ComplianceSummary `json:"summary"`

	// Issues lists all validation findings
	Issues []ComplianceIssue `json:"issues,omitempty"`

	// Metadata contains additional context
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ComplianceStatus string

type ComplianceSummary struct {
	// TotalChecks is the total number of checks run
	TotalChecks int `json:"totalChecks"`

	// Passed is the number of passed checks
	Passed int `json:"passed"`

	// Errors is the count of error-level issues
	Errors int `json:"errors"`

	// Warnings is the count of warning-level issues
	Warnings int `json:"warnings"`

	// Infos is the count of info-level issues
	Infos int `json:"infos"`

	// BlockingIssues is the count of issues that block release
	BlockingIssues int `json:"blockingIssues"`

	// FixableIssues is the count of auto-fixable issues
	FixableIssues int `json:"fixableIssues"`
}

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"`

	// Events define custom events emitted by the component.
	Events []ComponentEvent `json:"events,omitempty"`

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

	// Uses lists component IDs this component depends on.
	Uses []string `json:"uses,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"`

	// ThemingContract defines the external theming API for this component.
	ThemingContract *ThemingContract `json:"themingContract,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 ComponentEvent struct {
	// Name is the event name (e.g., "change", "submit", "close").
	Name string `json:"name"`

	// Description explains when this event is emitted.
	Description string `json:"description,omitempty"`

	// Bubbles indicates whether the event bubbles up the DOM tree.
	Bubbles bool `json:"bubbles,omitempty"`

	// Detail describes the event detail payload fields.
	Detail []EventDetailField `json:"detail,omitempty"`
}

type ComponentFixContext struct {
	ComponentID string `json:"componentId"`
	IssueType   string `json:"issueType"`

	// FilePattern suggests where to find the component.
	FilePattern string `json:"filePattern"`

	// PropsToAdd lists props that may need to be added.
	PropsToAdd []RequiredProp `json:"propsToAdd,omitempty"`

	// StylesToCheck lists CSS properties to verify.
	StylesToCheck []StyleCheck `json:"stylesToCheck,omitempty"`

	// TokensAvailable lists available design tokens for the fix.
	TokensAvailable map[string][]string `json:"tokensAvailable,omitempty"`

	// RelatedComponents lists components that may also need fixes.
	RelatedComponents []string `json:"relatedComponents,omitempty"`

	// AntiPatterns lists patterns to avoid when fixing.
	AntiPatterns []string `json:"antiPatterns,omitempty"`
}

type ComponentSummary struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Category    string `json:"category,omitempty"`
	Description string `json:"description,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 ContractIssue struct {
	// Field is the JSON path to the problematic field.
	Field string `json:"field"`

	// Message describes the issue.
	Message string `json:"message"`

	// TokenID is the affected token ID, if applicable.
	TokenID string `json:"tokenId,omitempty"`
}

type ContractReport struct {
	// ComponentID is the ID of the validated component.
	ComponentID string `json:"componentId"`

	// Passed indicates whether validation passed without errors.
	Passed bool `json:"passed"`

	// Errors are critical issues that must be fixed.
	Errors []ContractIssue `json:"errors,omitempty"`

	// Warnings are non-critical issues that should be addressed.
	Warnings []ContractIssue `json:"warnings,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 ContrastReqs struct {
	Text         string `json:"text,omitempty"`
	LargeText    string `json:"largeText,omitempty"`
	UIComponents string `json:"uiComponents,omitempty"`
}

type ContrastSuggestion struct {
	Token         string  `json:"token"`
	Value         string  `json:"value"`
	ContrastRatio float64 `json:"contrastRatio"`
	MeetsAA       bool    `json:"meetsAA"`
	MeetsAAA      bool    `json:"meetsAAA"`
	MeetsAALarge  bool    `json:"meetsAALarge"`
}

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 CustomValidator struct {
	// ID is a unique identifier for this validator.
	ID string `json:"id"`

	// Name is a human-readable name.
	Name string `json:"name"`

	// Domain describes what this validator checks.
	// Examples: "security", "performance", "i18n", "seo"
	Domain string `json:"domain"`

	// Tool is the validator tool identifier.
	Tool string `json:"tool"`

	// Type specifies how to invoke the tool.
	Type ValidatorType `json:"type"`

	// Command is the command or path to run.
	Command string `json:"command,omitempty"`

	// Config provides tool-specific configuration.
	Config map[string]any `json:"config,omitempty"`

	// Required indicates whether validation must pass for compliance.
	Required bool `json:"required,omitempty"`
}

type D2Options struct {
	// Direction: "right", "down", "left", "up"
	Direction string

	// ShowTokens includes token relationships
	ShowTokens bool

	// ShowEvents includes event flow
	ShowEvents bool

	// ShowSlots includes slot composition
	ShowSlots bool

	// ShowProps includes property lists
	ShowProps bool

	// GroupByCategory groups components by category
	GroupByCategory bool

	// Theme: "default", "neutral", "earth", "terminal", etc.
	Theme string

	// Sketch mode for hand-drawn look
	Sketch bool
}

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"`

	// ThemeBindings maps application tokens to component theming contracts.
	ThemeBindings []ThemeBindings `json:"themeBindings,omitempty"`

	// Validators references external validation tools for requirements delegation.
	// DSS defines requirements (e.g., WCAG AA in Accessibility); Validators specifies
	// which external tools perform the actual validation (e.g., agent-a11y, spectral).
	Validators *Validators `json:"validators,omitempty"`
}

type DesignSystemRef struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type DocsOptions struct {
	// OutputDir is the base directory for generated docs
	OutputDir string

	// ProjectName for titles and headers
	ProjectName string

	// ProjectURL for external links (e.g., GitHub repo)
	ProjectURL string

	// IncludeMermaid embeds Mermaid diagrams inline
	IncludeMermaid bool

	// IncludeD2 generates D2 diagram files
	IncludeD2 bool

	// IncludeTokens generates W3C tokens file
	IncludeTokens bool

	// MkDocsCompatible adds MkDocs-specific formatting (admonitions, etc.)
	MkDocsCompatible bool
}

type DocsOutput struct {
	// Files maps relative paths to content
	Files map[string]string
}

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 EvalOptions struct {
	// IncludeIssues includes detailed issue list (default: true)
	IncludeIssues bool `json:"includeIssues,omitempty"`

	// MinScore is the minimum acceptable score (1-5, default: 4)
	MinScore int `json:"minScore,omitempty"`

	// Categories to evaluate (default: all)
	Categories []string `json:"categories,omitempty"`

	// Verbose enables verbose output
	Verbose bool `json:"verbose,omitempty"`
}

type EventDetailField struct {
	// Name is the field name.
	Name string `json:"name"`

	// Type is the data type.
	Type string `json:"type"`

	// Description explains the field's purpose.
	Description string `json:"description,omitempty"`
}

type Fix struct {
	// Line is the line number (1-indexed)
	Line int `json:"line"`

	// Rule is the rule that triggered this fix
	Rule string `json:"rule"`

	// Original is the original code
	Original string `json:"original"`

	// Replacement is the fixed code
	Replacement string `json:"replacement"`

	// Description explains what was fixed
	Description string `json:"description"`
}

type FixLoopOptions struct {
	// MaxIterations is the maximum number of fix-validate cycles
	// Default: 3
	MaxIterations int `json:"maxIterations,omitempty"`

	// DryRun previews fixes without applying
	DryRun bool `json:"dryRun,omitempty"`

	// StopOnRegression stops if fixes introduce new violations
	StopOnRegression bool `json:"stopOnRegression,omitempty"`

	// Rules limits which rules to fix (empty = all fixable rules)
	Rules []string `json:"rules,omitempty"`

	// Files limits which files to process (empty = all)
	Files []string `json:"files,omitempty"`

	// Extensions limits file extensions to process
	Extensions []string `json:"extensions,omitempty"`
}

type FixLoopResult struct {
	// Converged indicates if the loop reached a stable state
	Converged bool `json:"converged"`

	// Iterations is the number of fix-validate cycles run
	Iterations int `json:"iterations"`

	// InitialViolations is the count before fixing
	InitialViolations int `json:"initialViolations"`

	// FinalViolations is the count after all fixes
	FinalViolations int `json:"finalViolations"`

	// FixedCount is the total number of issues fixed
	FixedCount int `json:"fixedCount"`

	// UnfixableCount is issues that couldn't be auto-fixed
	UnfixableCount int `json:"unfixableCount"`

	// Iterations detail for each cycle
	IterationDetails []IterationDetail `json:"iterationDetails"`

	// RemainingIssues lists issues that couldn't be fixed
	RemainingIssues []Violation `json:"remainingIssues,omitempty"`

	// Status is the final compliance status
	Status ComplianceStatus `json:"status"`
}

type FixOptions struct {
	// Rules limits fixes to specific rules (empty = all)
	Rules []string `json:"rules,omitempty"`

	// DryRun returns fixes without applying them
	DryRun bool `json:"dryRun,omitempty"`

	// IncludeOriginal includes original content in result
	IncludeOriginal bool `json:"includeOriginal,omitempty"`
}

type FixResult struct {
	// File is the path to the file
	File string `json:"file"`

	// OriginalContent is the original file content
	OriginalContent string `json:"originalContent,omitempty"`

	// FixedContent is the fixed file content
	FixedContent string `json:"fixedContent"`

	// Fixes contains all applied fixes
	Fixes []Fix `json:"fixes"`

	// Summary provides aggregate counts
	Summary FixSummary `json:"summary"`
}

type FixSummary struct {
	// TotalFixes is the number of fixes applied
	TotalFixes int `json:"totalFixes"`

	// ColorFixes is the number of color fixes
	ColorFixes int `json:"colorFixes"`

	// SpacingFixes is the number of spacing fixes
	SpacingFixes int `json:"spacingFixes"`

	// AccessibilityFixes is the number of accessibility fixes
	AccessibilityFixes int `json:"accessibilityFixes"`
}

type FixVerifyResult struct {
	// File that was processed
	File string `json:"file"`

	// ViolationsBefore the fix
	ViolationsBefore int `json:"violationsBefore"`

	// FixesApplied count
	FixesApplied int `json:"fixesApplied"`

	// ViolationsAfter the fix
	ViolationsAfter int `json:"violationsAfter"`

	// Improvement is violations reduced
	Improvement int `json:"improvement"`

	// Regressions is new violations introduced
	Regressions int `json:"regressions"`

	// Verified indicates if fix was successful
	Verified bool `json:"verified"`

	// Reason explains the verification outcome
	Reason string `json:"reason"`
}

type FocusReqs struct {
	Visible   bool   `json:"visible"`
	Order     string `json:"order,omitempty"`
	TrapFocus bool   `json:"trapFocus,omitempty"`
	InitialOn string `json:"initialOn,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 GeneratedBinding struct {
	// Component is the component ID.
	Component string

	// CSS is the generated CSS/SCSS content.
	CSS string

	// Warnings are non-fatal issues encountered during generation.
	Warnings []string
}

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 HTMLEvalCategory struct {
	Name       string
	Score      int     // 0-100 for progress bar
	IntScore   int     // 1-5
	ScoreLabel string  // "Excellent", "Good", etc.
	Weight     float64 // 0-1.0
	Passed     int
	Checks     int
}

type HTMLEvalCoverage struct {
	Components    HTMLEvalCoverageSection
	Foundations   HTMLEvalCoverageSection
	Patterns      HTMLEvalCoverageSection
	Accessibility HTMLEvalCoverageSection
	Overall       int
}

type HTMLEvalCoverageSection struct {
	Total      int
	Complete   int
	Percentage int
	Missing    []string
}

type HTMLEvalFinding struct {
	Severity       string
	SeverityClass  string
	ID             string
	Title          string
	Description    string
	Location       string
	Recommendation string
}

type HTMLOptions struct {
	// OutputDir is the output directory
	OutputDir string

	// Title is the documentation title
	Title string

	// EvalResult is optional evaluation data (rubric format)
	// Coverage is extracted from EvalResult.GetCoverage() if available
	EvalResult *rubric.Rubric

	// MkDocs enables MkDocs-compatible output mode.
	// When true, generates Markdown files with embedded HTML
	// instead of standalone HTML files.
	MkDocs bool
}

type HTMLPage struct {
	Title            string
	DesignSystemName string
	Version          string
	ActivePage       string
	CSS              template.CSS
	Content          template.HTML
	Components       []Component // For sidebar navigation
}

type IterationDetail struct {
	// Iteration number (1-indexed)
	Iteration int `json:"iteration"`

	// ViolationsBefore at start of iteration
	ViolationsBefore int `json:"violationsBefore"`

	// FixesApplied in this iteration
	FixesApplied int `json:"fixesApplied"`

	// ViolationsAfter at end of iteration
	ViolationsAfter int `json:"violationsAfter"`

	// NewViolations introduced by fixes (regression)
	NewViolations int `json:"newViolations"`

	// FilesModified in this iteration
	FilesModified []string `json:"filesModified"`
}

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 KeyboardReqs struct {
	Interactions map[string]string `json:"interactions,omitempty"`
	TabIndex     string            `json:"tabIndex,omitempty"`
	TrapFocus    bool              `json:"trapFocus,omitempty"`
}

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 LintCoverage struct {
	// ComponentsWithLLMContext is the percentage of components with LLM context
	ComponentsWithLLMContext float64 `json:"componentsWithLlmContext"`

	// ComponentsWithVariants is the percentage of components with variants
	ComponentsWithVariants float64 `json:"componentsWithVariants"`

	// ComponentsWithProps is the percentage of components with props
	ComponentsWithProps float64 `json:"componentsWithProps"`

	// TokensWithDescriptions is the percentage of tokens with descriptions
	TokensWithDescriptions float64 `json:"tokensWithDescriptions"`

	// TokensReferenced is the percentage of tokens referenced by components
	TokensReferenced float64 `json:"tokensReferenced"`
}

type LintIssue struct {
	// Path is the JSON path to the issue (e.g., "components[0].llm.intent")
	Path string `json:"path"`

	// Severity is "error", "warning", or "info"
	Severity string `json:"severity"`

	// Rule is the rule ID (e.g., "llm-context-required")
	Rule string `json:"rule"`

	// Message describes the issue
	Message string `json:"message"`

	// Component is the component ID if applicable
	Component string `json:"component,omitempty"`

	// Suggestion provides guidance on how to fix
	Suggestion string `json:"suggestion,omitempty"`
}

type LintOptions struct {
	// Rules limits linting to specific rules (empty = all)
	Rules []string `json:"rules,omitempty"`

	// MinScore is the minimum acceptable score (default: 0)
	MinScore int `json:"minScore,omitempty"`

	// IncludeSuggestions includes fix suggestions in output
	IncludeSuggestions bool `json:"includeSuggestions,omitempty"`
}

type LintResult struct {
	// Score is the completeness score (0-100)
	Score int `json:"score"`

	// Issues contains all lint findings
	Issues []LintIssue `json:"issues"`

	// Summary provides aggregate counts
	Summary LintSummary `json:"summary"`

	// Coverage provides completeness metrics
	Coverage LintCoverage `json:"coverage"`
}

type LintSummary struct {
	Errors   int `json:"errors"`
	Warnings int `json:"warnings"`
	Infos    int `json:"infos"`
}

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 MermaidOptions struct {
	// DiagramType: "graph", "flowchart", "classDiagram"
	DiagramType string

	// Direction: "TD" (top-down), "LR" (left-right), "BT", "RL"
	Direction string

	// ShowTokens includes token relationships
	ShowTokens bool

	// ShowEvents includes event flow arrows
	ShowEvents bool

	// ShowSlots includes slot composition
	ShowSlots bool

	// GroupByCategory groups components by their category
	GroupByCategory bool

	// Theme: "default", "dark", "forest", "neutral"
	Theme string
}

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 PackageGeneratorOptions struct {
	// OutputDir is the directory to write the package to.
	OutputDir string

	// Targets specifies which framework outputs to generate.
	Targets []PackageTarget

	// Scope is the NPM scope (e.g., "@plexusone").
	// If empty, derived from meta.
	Scope string

	// PackageName is the package name (default: "design-tokens").
	PackageName string

	// DryRun previews output without writing files.
	DryRun bool

	// IncludeReadme generates a README.md file.
	IncludeReadme bool
}

type PackageTarget string

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 PatternSummary struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Category    string `json:"category,omitempty"`
	Description string `json:"description,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 PromptOptions struct {
	// Format: "markdown" (default), "xml"
	Format string `json:"format,omitempty"`

	// ComponentIDs limits output to specific components (empty = all)
	ComponentIDs []string `json:"componentIds,omitempty"`

	// IncludeFoundations includes design tokens
	IncludeFoundations bool `json:"includeFoundations,omitempty"`

	// IncludeComponents includes component definitions
	IncludeComponents bool `json:"includeComponents,omitempty"`

	// IncludePatterns includes pattern definitions
	IncludePatterns bool `json:"includePatterns,omitempty"`

	// IncludeAccessibility includes a11y requirements
	IncludeAccessibility bool `json:"includeAccessibility,omitempty"`

	// IncludeAntiPatterns includes anti-pattern warnings
	IncludeAntiPatterns bool `json:"includeAntiPatterns,omitempty"`

	// MaxExamples limits code examples per component
	MaxExamples int `json:"maxExamples,omitempty"`
}

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"`

	// Constraints defines validation constraints for this prop.
	Constraints *PropConstraints `json:"constraints,omitempty"`
}

type PropConstraints struct {
	// Min is the minimum value (for numbers) or length (for strings).
	Min *float64 `json:"min,omitempty"`

	// Max is the maximum value (for numbers) or length (for strings).
	Max *float64 `json:"max,omitempty"`

	// Pattern is a regex pattern the value must match.
	Pattern string `json:"pattern,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 ReleaseGate struct {
	// Approved indicates if release is approved
	Approved bool `json:"approved"`

	// Reason explains the decision
	Reason string `json:"reason"`

	// BlockingIssues lists issues preventing release
	BlockingIssues []string `json:"blockingIssues,omitempty"`

	// Warnings lists non-blocking concerns
	Warnings []string `json:"warnings,omitempty"`

	// Score is the compliance score
	Score int `json:"score"`

	// Certificate is the compliance certificate if approved
	Certificate *ComplianceCertificate `json:"certificate,omitempty"`
}

type ReleaseGateOptions struct {
	// MinScore is the minimum acceptable score
	MinScore int `json:"minScore,omitempty"`

	// RequireZeroErrors requires no error-level issues
	RequireZeroErrors bool `json:"requireZeroErrors,omitempty"`

	// BlockingCategories lists categories that must pass
	BlockingCategories []string `json:"blockingCategories,omitempty"`

	// AllowWarnings allows release with warnings
	AllowWarnings bool `json:"allowWarnings,omitempty"`
}

type RequiredProp struct {
	Name     string `json:"name"`
	When     string `json:"when,omitempty"`
	Type     string `json:"type,omitempty"`
	Example  string `json:"example,omitempty"`
	ARIAAttr string `json:"ariaAttr,omitempty"`
}

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 RuleSeverity string

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 Service struct {
	// contains filtered or unexported fields
}

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 StyleCheck struct {
	Property string `json:"property"`
	Token    string `json:"token,omitempty"`
	MinValue string `json:"minValue,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 ThemeBindings struct {
	// Component is the ID of the component being themed (e.g., "button", "card").
	Component string `json:"component"`

	// SpecURL is an optional URL to fetch the component's spec (for external components).
	// Can be a local file path or HTTP URL.
	SpecURL string `json:"specUrl,omitempty" jsonschema:"format=uri"`

	// ThemeMode specifies which mode these bindings apply to: "light", "dark", or empty for both.
	ThemeMode string `json:"themeMode,omitempty" jsonschema:"enum=light,enum=dark"`

	// Strategy defines how to handle unmapped tokens.
	// - "explicit": Only use defined mappings, skip unmapped tokens
	// - "semantic": Auto-map by semantic field, fall back to defaults
	// - "inherit": Use component defaults for all unmapped tokens
	Strategy string `json:"strategy,omitempty" jsonschema:"enum=explicit,enum=semantic,enum=inherit"`

	// Mappings defines explicit token-to-token mappings.
	Mappings []TokenMapping `json:"mappings"`
}

type ThemeToken struct {
	// ID is a unique identifier for the token within the component (e.g., "background", "text-color").
	ID string `json:"id"`

	// CSSProperty is the full CSS custom property name (e.g., "--btn-background").
	CSSProperty string `json:"cssProperty"`

	// Semantic indicates the token's semantic purpose for auto-mapping.
	// Common values: "primary", "secondary", "accent", "danger", "warning", "success",
	// "neutral", "surface", "text", "text-muted", "border".
	Semantic string `json:"semantic,omitempty"`

	// Description explains what this token controls.
	Description string `json:"description,omitempty"`

	// DefaultLight is the default value for light mode.
	DefaultLight string `json:"defaultLight,omitempty"`

	// DefaultDark is the default value for dark mode.
	DefaultDark string `json:"defaultDark,omitempty"`
}

type ThemingContract struct {
	// Prefix is the CSS custom property prefix for this component (e.g., "--btn", "--card").
	Prefix string `json:"prefix"`

	// Description provides context about the component's theming approach.
	Description string `json:"description,omitempty"`

	// Tokens lists all customizable theme tokens for the component.
	Tokens []ThemeToken `json:"tokens"`
}

type TokenBindingResult struct {
	CSSProperty string
	Value       string
	Transform   string
	Source      string // "explicit", "semantic", "inherit"
}

type TokenMapping struct {
	// From is the application's token (e.g., "brand-primary-500", "colors.primary").
	From string `json:"from"`

	// To is the component's token ID (e.g., "background", "text-color").
	To string `json:"to"`

	// Transform is an optional CSS function to apply (e.g., "rgb", "hsl", "lighten(10%)").
	Transform string `json:"transform,omitempty"`
}

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

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

type TokenSummary struct {
	ID    string `json:"id"`
	Type  string `json:"type"`
	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 ValidateOptions struct {
	// Rules limits validation to specific rules (empty = all)
	Rules []string `json:"rules,omitempty"`

	// Extensions limits file types to check (default: .tsx, .jsx, .ts, .js, .css)
	Extensions []string `json:"extensions,omitempty"`

	// IncludeContext includes code snippets in violations
	IncludeContext bool `json:"includeContext,omitempty"`
}

type ValidationError struct {
	Field   string
	Message string
}

type ValidationResult struct {
	// Files is the number of files checked
	Files int `json:"files"`

	// Violations contains all findings
	Violations []Violation `json:"violations"`

	// Summary provides aggregate counts
	Summary ValidationSummary `json:"summary"`
}

type ValidationSummary struct {
	Errors   int `json:"errors"`
	Warnings int `json:"warnings"`
	Infos    int `json:"infos"`
	Passed   int `json:"passed"`
}

type ValidationTarget struct {
	// Type is "file", "directory", or "project"
	Type string `json:"type"`

	// Path is the file or directory path
	Path string `json:"path"`

	// FileCount is the number of files validated
	FileCount int `json:"fileCount"`

	// Commit is the git commit hash if available
	Commit string `json:"commit,omitempty"`

	// Branch is the git branch if available
	Branch string `json:"branch,omitempty"`
}

type ValidatorIssue struct {
	// Rule is the rule ID that was violated.
	Rule string `json:"rule"`

	// Severity is the issue severity.
	Severity string `json:"severity"` // error, warning, info

	// Message describes the issue.
	Message string `json:"message"`

	// Path is the location in code/spec where the issue was found.
	Path string `json:"path,omitempty"`

	// Line is the line number if applicable.
	Line int `json:"line,omitempty"`

	// Element is the DOM element or selector if applicable (for a11y).
	Element string `json:"element,omitempty"`

	// Help provides guidance on fixing the issue.
	Help string `json:"help,omitempty"`

	// HelpURL links to documentation.
	HelpURL string `json:"helpUrl,omitempty"`
}

type ValidatorResult struct {
	// ValidatorID identifies which validator produced this result.
	ValidatorID string `json:"validatorId"`

	// Tool is the tool name.
	Tool string `json:"tool"`

	// Domain is the validation domain (accessibility, api, custom).
	Domain string `json:"domain"`

	// Passed indicates overall pass/fail status.
	Passed bool `json:"passed"`

	// Issues contains validation findings.
	Issues []ValidatorIssue `json:"issues,omitempty"`

	// Summary provides aggregate statistics.
	Summary ValidatorSummary `json:"summary"`

	// Metadata contains tool-specific result data.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ValidatorSummary struct {
	// Errors is the count of error-level issues.
	Errors int `json:"errors"`

	// Warnings is the count of warning-level issues.
	Warnings int `json:"warnings"`

	// Infos is the count of info-level issues.
	Infos int `json:"infos"`

	// Passed is the count of passed checks.
	Passed int `json:"passed,omitempty"`

	// Total is the total number of checks run.
	Total int `json:"total,omitempty"`
}

type ValidatorType string

type Validators struct {
	// Accessibility references accessibility validation tools.
	// Requirements are defined in the Accessibility section; this specifies how to validate.
	Accessibility *AccessibilityValidator `json:"accessibility,omitempty"`

	// APIStyle references API style guide validators.
	APIStyle *APIStyleValidator `json:"apiStyle,omitempty"`

	// Custom references custom validation tools for other domains.
	Custom []CustomValidator `json:"custom,omitempty"`
}

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 Violation struct {
	// File is the path to the file
	File string `json:"file"`

	// Line is the line number (1-indexed, 0 if unknown)
	Line int `json:"line,omitempty"`

	// Column is the column number (1-indexed, 0 if unknown)
	Column int `json:"column,omitempty"`

	// Rule is the rule ID (e.g., "no-hardcoded-colors")
	Rule string `json:"rule"`

	// Message describes the issue
	Message string `json:"message"`

	// Severity is "error", "warning", or "info"
	Severity string `json:"severity"`

	// Component is the component ID if applicable
	Component string `json:"component,omitempty"`

	// Context is a code snippet for context
	Context string `json:"context,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 W3CFontFamily struct {
	Value       interface{}            `json:"$value"`
	Type        string                 `json:"$type,omitempty"`
	Description string                 `json:"$description,omitempty"`
	Extensions  map[string]interface{} `json:"$extensions,omitempty"`
}

type W3CToken struct {
	Value       interface{}            `json:"$value"`
	Type        string                 `json:"$type,omitempty"`
	Description string                 `json:"$description,omitempty"`
	Extensions  map[string]interface{} `json:"$extensions,omitempty"`
}

type W3CTokenFile struct {
	Schema string                 `json:"$schema,omitempty"`
	Color  map[string]*W3CToken   `json:"color,omitempty"`
	Space  map[string]*W3CToken   `json:"space,omitempty"`
	Size   map[string]*W3CToken   `json:"size,omitempty"`
	Radius map[string]*W3CToken   `json:"radius,omitempty"`
	Shadow map[string]*W3CToken   `json:"shadow,omitempty"`
	Font   map[string]interface{} `json:"font,omitempty"`
	Motion map[string]interface{} `json:"motion,omitempty"`
	ZIndex map[string]*W3CToken   `json:"zIndex,omitempty"`
}

type W3CTokensOptions struct {
	// Prefix for token names (e.g., "mde" → "mde.color.primary")
	Prefix string

	// IncludeDescriptions adds $description to tokens
	IncludeDescriptions bool

	// IncludeExtensions adds $extensions with DSS metadata
	IncludeExtensions bool
}

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"`
}