Malevich Roadmap (post-quiz update)

Last updated: 2026-05-18 Status: Architectural decisions finalized via 8-section quiz. Implementation scoping below.

This roadmap replaces the previous roadmap.md. It reflects the architectural model defined in 01-master-diff-merge.md and the 42 principles in 02-principles.md.

Version philosophy

• v0.1.0 (shipped) — Phase 2 close. 10 components, 109 tests. Existing main branch.
• v0.2.0 (planned) — Architectural refactor without scope expansion. Migrate v0.1.0 to new model (layer reorganization, token restructure, lint rules, naming standardization). Net component count stays ~10.
• v1.0 (target) — Full architectural model implementation. 53 components. Public launch readiness.
• v1.1 — Stabilization + additional components driven by community feedback.
• v2.0 — Multi-brand, shaders, advanced ready sections.

v0.2.0 — Architectural refactor

Goal: Bring v0.1.0 code into v1.0 architectural model without adding components. This is the migration step.

Scope:

Component reorganization

• Move Avatar: elements/avatar/ → foundations/avatar/
• Move Tabs: blocks/tabs/ → elements/interactive/tabs/
• Move Alert: blocks/alert/ → elements/display/alert/
• Reorganize Elements into sub-categories: elements/interactive/, elements/form/, elements/display/

Token system migration

• Restructure foundations.json into proper nested groups (color, space, radius, etc.)
• Restructure semantic.json with semantic groups (color.text, color.surface, color.border, etc.)
• Migrate all component CSS to consume only semantic + component-tier tokens
• Rename existing tokens following new convention

Modifier renaming

• Tweak prefix t- → modifier data-attributes (decision P-1.3 + P-7.1)
• Existing tweaks become formal modifiers in proper categories
• Component CSS updated to use namespace-scoped variables

Lint rules

• Implement no-foundation-direct-reference
• Implement modifier-namespace-check
• Fix existing no-raw-values Safari 1px detection bug
• Fix stylelint v16 deprecation warning

Documentation

• Update all 10 component docs.md files
• Generate sibling .agents.md for each component with token mapping
• Update llm-wiki manifesto, glossary, architecture docs

Migration tooling

• Codemod for token rename (CSS find/replace)
• File move script for layer reorganization
• Test rerun verification

Estimated work: ~40-60 hours total. Can be batched into 3-4 parallel tracks.

Definition of done:

• All v0.1.0 tests still pass (109 → likely 109 + new lint tests)
• New architectural model fully reflected in code
• Migration codemod tested and documented
• ADRs 0006-0012 written

v1.0 — Full architectural model

Goal: Ship all 53 v1.0 components with documentation, tests, and AGENTS.md.

Foundations (8 components, +6 net from v0.2.0)

• Avatar ✅ (migrated from Elements)
• Icon (NEW) — pluggable pack system, default @malevich/icons-default (Phosphor)
• Typography ✅ (already exists as classes)
• Divider (NEW) — horizontal/vertical, CSS-only
• Spinner (NEW)
• Skeleton (NEW)
• Dots (NEW) — inline loading indicator
• Image (NEW) — with <picture> support

Elements / Interactive (6 components, +3 net)

• Button ✅ — modified to 5 variants (primary/secondary/ghost/danger/success)
• Button-group (NEW)
• Tabs ✅ (migrated from Blocks)
• Switch (NEW)
• Toggle (NEW)
• Kbd (NEW)

Elements / Form (12 components, +11 net)

• Field-group (NEW) — composite wrapper
• Label (NEW)
• Input ✅
• Textarea (NEW)
• HelperText (NEW)
• Error (NEW) — form error display
• Select (NEW) — native styled
• Radio-group (NEW)
• Checkbox ✅
• Checkbox-group (NEW)
• Form-button (NEW) — separate from generic Button
• Form-divider (NEW) — with separation text

Elements / Display (6 components, +4 net)

• Badge ✅
• Tag (NEW) — dismissible label
• Tags-group (NEW) — overflow handling
• Avatar-group (NEW) — overlap stack
• Code (NEW) — inline code styling, copyable by default (built-in copy button on hover)
• Alert ✅ (migrated from Blocks)

Blocks (7 components, +5 net)

• Card ✅ — hybrid composition (slots + semantic tags + data-pattern)
• Accordion (NEW) — built on <details>
• Carousel (NEW) — minimal scope: scroll-snap, pagination, prev/next
• Breadcrumb (NEW)
• Code block (NEW) — multi-line with Shiki integration, copyable by default (built-in copy button in chrome)
• Quote block (NEW)
• State (NEW) — variants: empty/loading/error/success

Sections / Layout (4 components, +4 net)

• Block layout (NEW) — single-column container
• Split layout (NEW) — two-column with ratio
• Grid layout (NEW) — N-column uniform
• Stack layout (NEW) — vertical/horizontal stack

Sections / Ready (4 components, +4 net)

• Hero (NEW) — with patterns (standard/centered/split/minimal)
• CTA (NEW)
• Site-header (NEW) — with shape/surface/background/behavior modifiers
• Site-footer (NEW)

Overlays (6 components, +4 net)

• Dialog ✅
• Sheet (NEW) — 4-side slide-in, native <dialog>
• Tooltip ✅
• Popover (NEW) — click-triggered, Floating UI
• Toast (NEW) — individual notification
• Notifications (NEW) — stack manager, inspired by Sonner

Separate packages

• @malevich/icons-default (NEW) — Phosphor wrapped with adapter API
• @malevich/icons-lucide (NEW) — Lucide adapter
• @malevich/icons-tabler (NEW) — Tabler adapter
• @malevich/morph-icons ✅ — production API exists
• @floating-ui/dom — runtime dependency (Tooltip, Popover)

Token system extensions

• Display typography: hero/statement/title (fluid via clamp)
• Heading typography: title/section/subsection/group
• Body typography: lead/regular/support
• Special typography: caption/overline/eyebrow/code/mono (l/m/s)
• Color extensions: link colors, code colors, focus-ring, scrim
• Border extensions: on-inverse
• Size-control semantic tokens
• Border-width semantic tokens
• Motion presets (none/subtle/standard/expressive)
• Motion distance tokens

Modifier system implementation

• All 7 categories implemented
• Effect category: grain, glow, noise, ring, blur (5 values, CSS-only)
• Behavior category: sticky, dismissible, collapsible, copyable (runtime)
• Background category: solid, gradient, image (CSS)
• Applicability matrix as JSON
• Type generation pipeline
• AGENTS.md auto-generation per component

Documentation site

• Astro vanilla + MDX
• 47+ routes
• Sandbox iframe infrastructure
• Code tabs (HTML/CSS/JS/AGENTS.md)
• Theme switcher (Light/Dark/System)
• Pluggable icon pack picker (live demo)
• Modifier composer (live demo)
• llms.txt + llms-full.txt
• Full SEO (sitemap, OG, JSON-LD)
• Cloudflare Pages deployment to malevich.oleg.design

Quality bar

• All components: tests, docs.md, agents.md, _visual-reference.html
• Lighthouse 95+ on docs site
• @malevich/lint rules enforce architectural decisions
• Migration codemod from v0.1.x to v1.0

Estimated work: ~300-400 hours. Months, not weeks. Realistically v1.0 ships Q3 2026.

v1.1 — Stabilization & expansion

Goal: Address community feedback, add components held back from v1.0.

Additional components

• Toggle-group — single-select or multi-select toggle stack
• Slider — with full keyboard nav, custom Floating UI tooltips for value display
• Pagination — first/prev/N/next/last with truncation
• Multiselect — custom dropdown with search, multi-select
• Quote (inline) — small inline blockquote
• Popup — lightbox-style overlay for images/videos
• Context menu — right-click contextual actions
• Banner — full-width promotional area
• Stat — single metric display block

Token system upgrades

• W3C Design Tokens Community Group spec compliance — proper $type/$value structure, validation
• Figma Tokens Studio integration — round-trip token sync with Figma
• High contrast theme variant — accessibility-driven palette

Carousel enhancements

• Auto-play option
• Infinite loop
• Fade transition variant
• Vertical orientation

Layout additions

• Bento layout — asymmetric grid with explicit tile sizes
• Masonry layout (native CSS only) — pending CSS Grid Level 3 stabilization

Tooling

• Custom DevTools extension — inspect modifiers + computed CSS variables
• tier-respect lint rule — full enforcement of token reference order
• Runtime modifier debugger API — getModifiers(element), getActiveTokens(element)

SSR support

• Cookie-based theme detection
• Server-side preference (logged-in users)

Estimated work: ~100-150 hours.

v2.0 — Multi-brand, shaders, advanced sections

Goal: Enterprise features, advanced visual capabilities, pattern promotion.

@malevich/shaders

• WebGL-powered interactive backgrounds
• Mesh gradients
• Particle flow
• Reactive glow (cursor-driven)
• Fluid dynamics simulation
• Shader-as-modifier API: data-shader="mesh-gradient"
• Performance budgeting (max instances per page)
• CSS fallback chain

Multi-brand support

• Multiple semantic theme files per project
• Brand switching API: data-brand="acme"
• Per-brand asset overrides (fonts, logos)
• Theme pack format specification
• Community theme pack ecosystem

Advanced ready sections

• Testimonials — opinionated section with multiple layout patterns
• Pricing — multi-tier pricing with comparison, annual/monthly toggle
• FAQ — promoted from composition pattern to opinionated section
• Newsletter — opinionated subscription section
• Cookie banner — UI primitive with consent integration patterns documented

Inline composites

• Inline-form-group — 1-3 inputs + submit button for inline searches, filters, subscriptions

Masonry runtime

• JS-backed masonry fallback when native CSS unavailable
• Lazy-load tile rendering
• Resize observer integration

Ask AI button

• Floating chat island bottom-center
• Backend: Cloudflare Workers AI or similar
• Retrieval over content collections + AGENTS.md files
• Mobile overlay variant

Component versioning

• Per-component version tracking (in addition to package version)
• "Available since v1.X" annotations in docs
• Deprecation lifecycle with codemod paths

Estimated work: ~200-300 hours. Could span multiple quarters depending on community traction.

Cross-cutting work

Documentation maintenance

• Live demos for every component variant
• Live demos for every modifier combination
• AGENTS.md kept in sync with component changes
• Token-to-component mapping documented per component
• Migration guides for each major version

Tooling maintenance

• @malevich/lint rule updates per architectural changes
• @malevich/core token pipeline updates for spec changes
• @malevich/cli for project scaffolding (v1.1+)

Community

• Contribution guidelines
• RFC process for new components
• Theme pack submission format
• Icon pack adapter contributions

Out of roadmap (out of scope for foreseeable future)

• Chart components — delegated to Recharts, Visx, D3, Tremor
• Date pickers — too complex, recommend external (react-day-picker etc.)
• Rich text editor — out of DS scope
• File uploaders — context-specific, varies by backend
• Email template components — different rendering context
• Drag-and-drop libraries — out of DS scope, recommend external
• Authentication UIs — too product-specific
• Internationalization — Malevich tokens are i18n-aware, but message translation is product domain

Decision points along the way

These are architectural questions deferred for later decisions. They will likely be discussed before v1.1 or v2.0 ship.

1. Native CSS masonry adoption — pending browser support. If stable by v1.1, native; if not, defer to v2.0 with JS fallback.
2. Custom Select component — if community demands rich dropdowns, custom Select replaces native styled in v1.1. Otherwise stays native.
3. Shader bundle splitting — if @malevich/shaders becomes large, split into core + extensions packages.
4. i18n token category — RTL support, locale-specific font-family overrides may warrant a dedicated semantic group.
5. Animation framework integration — Framer Motion / Motion One vs CSS-only. Currently CSS-only by principle, may revisit if complex animations become common request.