Skip to content

library-scope.md

Latest commit

 

History

History
133 lines (105 loc) · 5.02 KB

library-scope.md

File metadata and controls

133 lines (105 loc) · 5.02 KB
Raw

Library scope

Mado UI is complete enough for v1 when a team can build a product site, SaaS application, administration surface or documentation project without adding a second general-purpose UI library.

This is a product boundary, not a promise to reproduce every component found in larger ecosystems. Mado UI prefers a smaller native-first contract over multiple overlapping abstractions.

Baseline and target

The plan was adopted with 13 registry items already implemented:

  • one foundation;
  • eight primitives;
  • four blocks.

The current registry contains 44 items: one foundation, 18 primitives, 19 blocks and six templates. The count is close to the lower planning boundary, but stability and real application fit still decide readiness.

The expected v1 is approximately 45–55 registry items. Item count is only a rough planning signal: a native CSS recipe is much cheaper than a composite widget with focus management, and one item may cover several related native elements.

Milestone Outcome Approximate total
v0.2 Forms, navigation, data presentation and application states 25–30 items
v0.3 Interactive native-first widgets with complete keyboard contracts 35–42 items
v0.4 Reusable application blocks and representative templates 45–55 items
v1 Contract hardening, migrations, versioned documentation and release 45–55 stable items

At the adopted baseline the item count is roughly one quarter of the v1 target, while the completed behavioral complexity is closer to one fifth. Dialog, menu, tabs, combobox and similar widgets carry a larger accessibility and lifecycle cost than CSS-only primitives.

Milestone families

v0.2 — complete application basics

  • Field, description and validation message.
  • Form section and settings row.
  • Breadcrumbs and navigation list.
  • Avatar and separator.
  • Skeleton and empty/loading/success/warning/error states.
  • Description list.
  • Readable long-form document content for guides and policies.
  • Metric card and metric grid.
  • Responsive native-table shell.
  • Pagination and filter/action bar.

v0.3 — interactive layer

  • Native dialog.
  • Browser Popover API composition.
  • Dropdown menu.
  • Tooltip.
  • Disclosure/accordion built on details.
  • Tabs with a tested keyboard model.
  • A native-first in-flow notification region with a separate stable status announcer.
  • Combobox/listbox.
  • Command palette.
  • Responsive navigation popover with a bounded scrolling link region, pinned footer and lifecycle that also covers dynamically rendered links.

These items use browser primitives first. A Mado component is introduced only when application state or behavior cannot be expressed honestly with HTML and CSS.

v0.4 — composition and templates

  • Application shell.
  • List/data page.
  • Detail page.
  • Edit form.
  • Settings page.
  • Authentication shell.
  • Marketing/documentation layouts, once the Mado site proves a reusable shape.

Templates prove that foundations, primitives and blocks compose into real applications. Product-specific data, routing and language remain outside the registry. The first six application recipes are implemented; another layout is a candidate discovered from product work, not a quota.

Work organization

Work proceeds in vertical families of two to four related items. A family includes source, registry metadata, CLI behavior, catalog examples, documentation and acceptance coverage in one change. Avoid separate “component first, accessibility later” phases.

At 44 items, the remaining work is primarily contract hardening, complete catalog reference content, release mechanics and validation in a real Mado application. New vertical families should be opened only for repeated product needs; item count must not be used as a deadline shortcut.

Use the developing Mado site as a consumer and source of real requirements. Do not add an item only to increase catalog breadth.

Definition of done

A public item is complete only when all applicable checks pass:

  • Registry schema, dependency graph and package contents.
  • Safe view, add, diff and doctor behavior.
  • Public source remains readable and application-owned.
  • No browser runtime dependency is added by @madojs/ui.
  • Correct native semantics and keyboard behavior.
  • Focus visibility and native disabled behavior.
  • 320 px layout and 200% text scaling.
  • Light, dark and forced-colors presentation.
  • Reduced-motion behavior when animation exists.
  • Real-browser catalog coverage.
  • Install command, dependencies, API and accessibility contract are documented.

Interactive items additionally require a written focus model before their implementation begins.

Non-goals for v1

  • A bundled browser runtime imported from @madojs/ui.
  • A second design token system owned by the catalog or the Mado site.
  • Domain-specific states or business components.
  • A complete icon set or runtime icon dependency.
  • Multiple components with overlapping semantics.
  • Remote registries or namespaces before a concrete third-party registry exists.