Foundation

Versioningv1.5.0 · 2026-04-08

The Nodus Design System uses semantic versioning for individual component stability, sprint labels to communicate when each component was introduced, and an explicit deprecation policy to give consumers time to migrate.

01 — Semantic Versioning Rules

Every component carries a version field in the registry. The design system as a whole follows semver 2.0 with these bump rules:

x.x.N

Patch

Bug fixes, WCAG contrast corrections, token alignment fixes

e.g. Fix text contrast ratio, align spacing token usage

x.N.0

Minor

New props, new variants, new sizes — all backwards-compatible

e.g. Add `size="xl"` to Button, add `ghost` variant to Badge

N.0.0

Major

Breaking changes: prop renames, removed variants, API rewrites

e.g. Rename `variant="primary"` to `variant="filled"`, remove deprecated flag

02 — Sprint Labels (since)

The since field records which sprint first introduced a component. Component pages link back here so consumers can trace the component's provenance.

Sprint	Label	Theme	Representative Components
S1	Foundation	Core UI primitives	Button, Badge, Input, Typography, Chip, Divider, Spinner
S2	Structure	Layout + navigation	Accordion, Table, Tabs, Modal, Pagination, Sidebar, Skeleton
S3	Agency	Agentic pattern layer	AgentMessage, ApprovalQueue, ConsentFlow, AgentIdentityBadge
S4	Finance	Finance domain primitives	CashPositionCard, FXRateCard, LiquidityGauge, TradeTicket
S5	Edge States	Failure + timeout patterns	AgentUnavailable, PartialCompletion, TimeoutIndicator, StaleProvenance
S6	Reasoning	Agent reasoning UI	ReasoningTrace, LearningLog, AvatarStack, ConflictLayout
S7	Visualization	Token Explorer + data viz	TokenExplorer, ChartPrimitive, PortfolioRiskOverview
S8	Motion	Motion tokens + light mode parity	Motion system, light mode WCAG AA audit across all 35 patterns
S9	Identity	Iconography + type exports	Icon (16 icons), TypeScript barrel, dataviz chart primitives
S10	Release	v1.0 release artifacts	Release Notes page, Intercompany Netting template
S11	Versioning	Component versioning system	DeprecationBanner, version badges, this page

03 — Deprecation Policy

Deprecation Guarantee

A deprecated component is never removed in the same sprint it is marked deprecated. Consumers have at least one full sprint to migrate before removal.

Mark in registry

Set deprecated: true and deprecationNote in the component's registry entry. The DeprecationBanner renders automatically on the component page.

Migration note

The deprecationNote must specify the replacement component or link to a migration guide. Vague notes like "use something else" are not acceptable.

One-sprint grace period

The component stays in the codebase and builds for at least one sprint after deprecation. No runtime errors — existing consumers continue to work.

Removal

Remove the component source, registry entry, and demo in a subsequent sprint. Record the removal in CHANGELOG.md with the final sprint label.

04 — Registry Fields

Field	Type	Required	Description
`version`	string	optional	Semver string. Defaults to "1.0.0" for existing stable components.
`since`	string	optional	Sprint label such as "S1" or "S9". Auto-assigned by category if omitted.
`deprecated`	boolean	optional	Set true to trigger DeprecationBanner on the component page.
`deprecationNote`	string	conditional	Required when deprecated=true. Describes the replacement or migration path.

← Release Notes Accessibility →