DEV Community: Vellira

From Scaffold to Production: How Vellira Generates Components

Vellira — Wed, 30 Sep 2026 08:00:00 +0000

A component generator becomes useful when it stops thinking in terms of files and starts thinking in terms of product surfaces.

Creating this:

Component.tsx

is the easy part.

In a real design system, a component may also need:

public types,
package exports,
tests,
Storybook,
metadata,
documentation,
platform-specific behavior,
website examples,
playground configuration,
validation contracts.

If all of those surfaces are created manually, they drift.

If they are generated without clear ownership, regeneration becomes dangerous.

So Vellira's component generator is built around a different idea:

Describe component intent once, turn it into a deterministic plan, and generate the repeatable repository contract around it.

`Component.tsx` is only one node

A minimal generator might do this:

input: Button

output:
Button.tsx

That saves some typing.

But it does not solve most of the repetitive work around a production component library.

A real component can touch:

runtime implementation
public types
local exports
package exports
API contracts
tests
Storybook
styles / tokens
metadata
docs
website examples
catalog registries

The source file is just one node in that graph.

If the generator creates only the implementation, it automates the cheapest part while leaving most consistency risk with humans.

The more useful question is:

What do we already know about this component before generation, and which repository surfaces can be derived from that information deterministically?

Start with explicit intent

Vellira's generator does not only ask for a component name.

The public CLI expresses things such as:

pnpm create:component \
  <Name> \
  <platform> \
  <layer> \
  <category> \
  [--profile=<profile>] \
  [--capabilities=controlled,keyboard,...] \
  [--parts=Root,Trigger,Content] \
  [--dry-run] \
  [--check]

Some of those inputs describe product structure:

platform
layer
category
profile
capabilities
parts

Profiles represent reusable component families:

base
form-control
compound
overlay

The key is that these are reusable architectural concepts.

The generator should understand:

compound component

rather than:

if componentName === "Tabs"

Profiles beat component-name heuristics

This is fragile:

if name === "SomeInput":
  generate form state

if name === "SomeTabs":
  generate compound parts

if name === "SomeModal":
  generate overlay behavior

The generator slowly becomes a database of product names.

Instead, reusable intent can be explicit:

profile=compound
parts=Root,List,Trigger,Content
capabilities=controlled,uncontrolled,keyboard,focus-management

A Tabs-like component might therefore be described structurally:

pnpm create:component Tabs both components navigation \
  --profile=compound \
  --capabilities=controlled,uncontrolled,keyboard,focus-management \
  --parts=Root,List,Trigger,Content

The important thing is not the exact command.

It is that the generator receives facts, not hidden assumptions attached to the word Tabs.

That makes the system easier to test and extend.

Plan React and React Native together, generate them separately

When a component targets both runtimes, Vellira resolves two targets:

packages/react/...
packages/react-native/...

They share component identity and product intent.

But each runtime can still have its own:

implementation,
public API extensions,
tests,
styles,
accessibility semantics,
interaction behavior.

This matters because cross-platform does not mean identical source code.

Web may use:

DOM
CSS
keyboard events
focus APIs
ARIA
portals

React Native may use:

Pressable
TextInput
native accessibility props
touch interaction
native styles
Modal / native presentation

The generator should preserve shared intent without pretending that both runtimes are the same environment.

Generate the surrounding product surface

Once the plan is valid, generation can produce much more than the runtime component.

Depending on the profile, the output may include:

types.ts
index.ts
Component.tsx
Component.test.tsx
Component.stories.tsx
test contracts
styles
compound parts
metadata
docs contracts
component token files

It can also update existing repository-owned surfaces such as:

layer exports
package root exports
public API contracts
metadata registry
docs registry

And the component pipeline can hand off to the website component-page generator to create things like:

usage,
examples,
accessibility sections,
API data,
playgrounds,
React demos,
React Native demos,
catalog registration.

At that point it is no longer just a file generator.

It is encoding part of the production lifecycle.

Public exports should not depend on memory

Exports are an easy thing to forget.

A component can work perfectly inside its own directory and still be unusable to consumers because the package root never exposes it.

So generation should move through the whole public boundary:

component
    ↓
layer export
    ↓
package root export
    ↓
public API contract

The same principle applies to metadata and documentation registries.

If a repeatable registration step is required every time, it is a good candidate for deterministic generation.

Generate test requirements, not empty test files

An empty generated test file is not much of an improvement.

The baseline test contract should come from the same component intent.

Conceptually:

profile
+ capabilities
+ platform
        ↓
baseline test contract
        ↓
generated test expectations

A form control and a compound navigation component should not receive the same baseline.

For example, a form control may need evidence for:

controlled
uncontrolled
disabled
required
invalid

while a compound navigation component may care about:

keyboard
focus-management
controlled
uncontrolled
compound-api

The generator and the test system should describe the same component.

Regeneration needs ownership boundaries

First-time generation is easy compared with regeneration.

Once humans have added meaningful engineering work, --force cannot simply mean:

delete everything
generate everything again

unless every file is truly generator-owned.

A safer model is:

generator-owned surface
→ may be regenerated

manual extension / semantic engineering
→ must be preserved

This distinction is critical.

If developers cannot trust regeneration, they stop using it.

Once that happens, generated surfaces begin drifting permanently.

Fail before writing

A generator touching many parts of a monorepo should validate the plan before mutation.

Preflight can check things such as:

required barrels exist,
registries are structurally valid,
profile/parts combinations are valid,
requested canonical resources exist,
target paths do not conflict,
overwrite was explicitly authorized.

The principle is:

A bad plan should fail before it leaves a half-generated component behind.

This becomes even more important when one generation operation updates multiple packages and registries.

`--dry-run` is a safety feature

A generator with broad repository reach should be previewable.

Vellira supports a dry-run mode so you can inspect things like:

which packages will change?
which files will be created?
which registries will be updated?
which platforms were resolved?
which profile did the intent select?

before any write happens.

That makes generation reviewable.

And reviewability is part of safety.

Idempotency is part of the contract

A deterministic generator should converge.

Run the same authorized generation twice and the second run should not create:

duplicate exports,
duplicate registry entries,
reordered files,
formatting churn,
unrelated changes.

That requires stable:

ordering,
formatting,
serialization,
registration logic.

Generated surfaces should also support check mode.

For example:

pnpm create:component-page <Component> --check

can verify that checked-in generated output still matches its canonical input without rewriting it.

This gives CI a way to catch generated drift.

Downstream generators should still have boundaries

One deterministic tool can call another.

But that does not mean it should blindly trust every mutation.

For example:

component generator
       ↓
website component-page generator

can be a useful composition.

But the orchestrating layer should still know which artifacts are expected to change and detect unexpected disappearance or corruption.

Automation should compose contracts, not remove them.

What the generator should not decide

This may be the most important boundary.

The generator should not try to finish product design.

A compound scaffold can create:

Root
List
Trigger
Content

but it should not invent every interaction decision for every future compound component.

An overlay profile can establish structure.

It should not pretend to solve every focus, dismissal, presentation, and accessibility edge case.

A form-control profile can establish state foundations.

It should not decide every future Input-like API.

A useful split is:

deterministic generator owns
--------------------------------
repository placement
repeatable file structure
exports and registrations
baseline contracts
starter tests
starter stories
metadata scaffolding
generated docs/page plumbing
overwrite/check rules

component engineering owns
--------------------------------
final product semantics
nuanced API decisions
complex accessibility behavior
runtime interaction details
visual refinement
important edge cases

The first category exists to give engineers more time for the second.

Fix systemic gaps once

This is where a production generator becomes really valuable.

Suppose several components reveal the same missing export behavior.

You can repair each component manually.

Or you can fix the generator once.

The same applies to:

tests
Storybook
metadata
docs
website pages
tokens
platform templates

Every repeated failure is a chance to improve the production path.

That changes how the design system grows.

The next component inherits the fix automatically.

The generator is not primarily a typing shortcut

That is probably the biggest lesson from building this.

A serious component generator is a way to encode the repeatable production contract of a component library.

For Vellira, that contract now connects things like:

intent
  ↓
generation plan
  ↓
React / React Native targets
  ↓
implementation + public surface
  ↓
tests + stories + metadata + docs
  ↓
validation
  ↓
review

The component implementation still matters.

But Component.tsx no longer has to carry the entire meaning of “done.”

That is the real value of the generator.

It moves predictable repository work out of human memory and into a system that can be validated, repeated, and improved once for every component that comes after it.

Vellira is an open-source React and React Native design system being built in public.

Why We Built Quality Gates Before Growing to 20 Components

Vellira — Mon, 28 Sep 2026 08:00:00 +0000

A component library can look healthy while quietly accumulating consistency debt.

The build is green.

The package compiles.

Storybook opens.

The component renders in React and React Native.

Then somebody notices:

the public export is missing,
the website API is stale,
Storybook only covers the happy path,
the component claims keyboard support without deterministic evidence,
or the native implementation does not actually match the declared contract.

None of those failures necessarily breaks compilation.

That is why, before rapidly growing Vellira's component catalog toward 20 components, we invested in deterministic completeness and quality gates.

The goal was not more infrastructure.

The goal was cheaper trust.

Component count is a misleading progress metric

A design system can grow from 10 components to 20 and become less reliable.

Component count tells you very little about whether those components are:

exported correctly,
documented,
tested,
accessible,
represented in Storybook,
aligned across platforms,
using canonical design resources.

A production component is usually much more than:

Component.tsx

It may also require:

implementation
public types
package exports
tests
Storybook
website documentation
examples
API documentation
accessibility evidence
metadata
tokens
platform-specific validation

So adding ten components does not add ten things.

It can add roughly a hundred new surfaces capable of drifting.

A more useful question is not:

How many components do we have?

It is:

How many component contracts can the repository actually prove are complete?

A green build proves less than it feels like it proves

Build success matters.

But a compiler or bundler mostly tells you that the code can be transformed into valid output.

It usually does not tell you that:

the intended component is exported from the package root,
a public Props contract exists,
controlled and uncontrolled behavior are actually tested,
disabled or invalid states have executable evidence,
Storybook exposes representative states,
component documentation is current,
React Native has platform-appropriate accessibility semantics,
an overlay actually has presentation behavior on both runtimes.

A design system has a much larger product surface than its build graph.

That is why ordinary build validation is necessary but insufficient.

Completeness and quality are different questions

This distinction became important in Vellira.

Completeness asks:

Did we ship every repository surface required by this component?

Quality asks:

Do those surfaces contain credible evidence for the contract we claim?

Those are not the same thing.

A test file can exist and test almost nothing.

A Storybook file can exist while showing only Default.

Documentation can exist while containing stale or generic content.

A component can have an implementation but still be missing the public API consumers expect.

So we keep the two layers separate.

Completeness: is the whole component actually there?

Vellira's completeness checks begin from canonical component metadata.

For a component, the contract may say:

platforms: React + React Native

tests: required
Storybook: required
docs: required
accessibility: required
tokens: required

The repository can then derive what should exist.

Conceptually:

component contract
        ↓
expected repository surfaces
        ↓
actual repository
        ↓
COMPLETE / INCOMPLETE

If React Native is declared but the native implementation does not exist, that should not depend on somebody noticing during review.

It should fail deterministically.

The same applies to:

types,
exports,
tests,
stories,
documentation,
accessibility surfaces,
token requirements.

Quality: does the evidence support the claim?

Existence alone is not enough.

Suppose a form component declares:

controlled
uncontrolled
disabled
required
invalid

A single happy-path test technically satisfies:

test file exists

But it does not provide evidence for those behaviors.

A quality gate can ask for something stronger:

controlled behavior → evidence
uncontrolled behavior → evidence
disabled behavior → evidence
invalid behavior → evidence

This is where the distinction becomes useful:

Completeness:
Does the required test surface exist?

Quality:
Does that test surface prove important declared behavior?

The same idea applies elsewhere.

Storybook is a product surface too

A *.stories.tsx file existing is not automatically useful coverage.

Imagine a component that supports:

default
disabled
loading
invalid
controlled
uncontrolled

but Storybook shows only:

Default

Technically, Storybook coverage exists.

Practically, the observable component contract is poorly represented.

So representative states matter too.

Not every missing story needs to block CI — severity can differ — but the system should at least know the difference between:

story file exists

and:

important states are visible

Documentation can drift independently of code

This is another place where green builds provide very little protection.

A component implementation can be correct while:

its website page is stale,
generated API information is outdated,
the accessibility section is missing,
React Native differences are undocumented,
component-page registration is duplicated or broken.

Generated documentation does not eliminate this problem.

Generated output can become stale too.

So a useful pattern is:

generate
   ↓
check freshness
   ↓
audit resulting structure

Generation reduces manual work.

Validation prevents generated output from becoming another silent source of drift.

Public APIs deserve their own checks

Design systems are libraries.

That makes package boundaries part of the product.

An implementation might work inside the monorepo while consumers still cannot import it correctly.

For example:

implementation exists
        ↓
internal imports work
        ↓
package root export missing
        ↓
consumer cannot use component

The build may still succeed.

So exports and public type contracts need explicit validation.

For reusable libraries, the public API is not incidental infrastructure.

It is part of the product itself.

Cross-platform components need independent evidence

This becomes especially important with React and React Native.

Shared semantics do not imply shared implementation evidence.

For accessibility, Web might rely on:

semantic HTML
roles
ARIA attributes

while React Native uses:

accessibilityRole
accessibilityLabel
accessibilityState
accessibilityHint

A useful quality system should understand that these are different implementations of related product responsibilities.

The same is true for:

keyboard interaction,
focus management,
gestures,
overlays,
presentation mechanisms.

Cross-platform validation should preserve shared intent while checking each runtime honestly.

Overlays expose weak parity very quickly

Consider an overlay-like component.

The contract may say that it has:

controlled state
uncontrolled state
focus management
keyboard behavior
compound API
portal/presentation behavior

On the Web, presentation might involve a portal.

On React Native, it may involve Modal or another platform-native mechanism.

The important requirement is not:

Does the native source code resemble the web source code?

It is:

Does each runtime provide credible evidence for the same product responsibility?

This is why platform-aware gates matter.

A shared TypeScript API alone cannot prove runtime parity.

Small deterministic checks compose better

One thing we deliberately avoid is one enormous:

validate-everything

script.

Instead, different contracts answer different questions.

For example:

build
→ can this package be produced?

public API
→ can consumers access what we claim?

completeness
→ are all required surfaces present?

quality
→ is there credible evidence for the declared contract?

docs audit
→ is the public documentation structurally valid?

tests
→ does runtime behavior match expectations?

When something fails, the failure should explain the actual problem.

That makes the system easier to debug and easier to evolve.

Structured findings are more useful than log text

Once a quality rule represents a stable engineering judgment, its result should be reusable.

Instead of only printing:

something is wrong with Select

a structured finding can contain:

rule id
dimension
severity
platform
status
message
evidence

That can later support:

CI output,
review summaries,
issue synchronization,
historical comparison,
automated routing.

The rule stays deterministic.

Different consumers can decide how to present its result.

Automate memory, not engineering judgment

There is an important limit here.

A checker can verify that a Props contract exists.

It cannot prove that every prop is well designed.

A checker can detect accessibility semantics.

It cannot prove every real user experience is accessible.

A Storybook rule can detect representative states.

It cannot decide whether the examples explain the component well.

A documentation audit can reject empty descriptions.

It cannot write excellent documentation.

So the target is not:

automate component quality completely

It is:

automate repeated deterministic invariants so humans can spend review time on the decisions that actually require judgment.

That boundary matters.

Fix repeated failures at the system level

This is where quality gates become especially valuable.

Imagine five form controls all reach review without invalid-state coverage.

You could fix five test files.

Or you could ask:

Why could five components reach this point with the same omission?

Maybe the reusable fix belongs in:

generator templates
metadata
test contracts
quality rules
documentation generation
CI

Then every future component benefits.

That is the difference between fixing a component and fixing the component-production system.

Why a bounded target like 20 components helps

There is nothing magical about the number 20.

The useful part is the constraint.

A bounded catalog gives enough variety to exercise:

primitives
form controls
compound APIs
navigation
overlays
React
React Native
controlled state
keyboard interaction
focus management
tokens
icons

while the repository is still small enough to audit completely.

That creates a good moment to strengthen the production system.

If you grow the catalog first and introduce quality contracts later, every new rule may uncover years of historical inconsistency.

It is much cheaper to establish the rules while the system is still manageable.

Quality gates are cheapest before you desperately need them

This is similar to database constraints.

Adding a constraint before millions of invalid rows exist is much easier than retrofitting one afterward.

For a design system, early gates establish expectations around:

public APIs,
testing,
Storybook,
documentation,
accessibility,
platform parity,
metadata,
design resources.

New components then enter an existing definition of done.

They do not invent their own.

The goal is cheaper trust

Quality gates can sound restrictive.

I think their more important role is the opposite.

They reduce the amount of repeated verification humans need to perform.

When another component enters the catalog, review should not begin by rediscovering whether:

exports matter,
tests matter,
accessibility matters,
documentation matters,
Storybook matters,
platform evidence matters.

Those expectations should already be part of the system.

Human review should focus on what is actually new about the component.

That is why we built the gates before aggressively growing the Vellira catalog.

Not because infrastructure is more important than components.

Because components become easier to ship confidently when the surrounding system can prove the repeated parts of production readiness.

The goal is not maximum automation.

The goal is more components without multiplying uncertainty at the same rate.

Vellira is an open-source React and React Native design system being built in public.

Component Metadata as a Source of Truth for a Design System

Vellira — Fri, 25 Sep 2026 08:00:00 +0000

A design system starts drifting long before anyone notices a broken component.

The first warning signs are usually quieter.

The website says a component supports React Native, but the native package does not export it.

Storybook has a story, but the component page is missing.

One checker assumes tests are required while another does not know the component is supposed to support keyboard interaction.

A generator creates a component, but someone still has to remember to update several registries by hand.

None of those failures starts inside the component implementation itself.

They start because the same facts are being maintained in too many places.

In Vellira, we address that with machine-readable component metadata: one canonical registry describing stable product and tooling facts about every component.

Generators, documentation tooling, completeness checks, and quality validation can then consume the same contract instead of rediscovering those facts independently.

The hidden cost of five component lists

Imagine maintaining separate lists for:

package exports
website catalog
Storybook expectations
documentation requirements
quality checks

With five components, that may be fine.

With twenty, every component starts carrying more context:

name
layer
category
platforms
status
capabilities
dependencies
required engineering surfaces

A component may be Web-only.

Another may support React and React Native.

A form control needs required and invalid states.

A navigation component needs keyboard behavior.

An overlay may require focus management and a portal.

Once those facts exist in several places, drift becomes almost inevitable.

Every change becomes several opportunities to forget something.

Automation helps.

But automation still needs an authority.

That is where metadata becomes useful.

What belongs in component metadata?

A simplified version of Vellira's component contract looks like this:

interface ComponentMetadata {
  name: string;

  layer:
    | 'primitives'
    | 'components'
    | 'patterns';

  category:
    | 'action'
    | 'form'
    | 'navigation'
    | 'overlay'
    | 'feedback'
    | 'data-display'
    | 'layout'
    | 'utility';

  platforms: readonly (
    | 'react'
    | 'react-native'
  )[];

  profile:
    | 'base'
    | 'form-control'
    | 'compound'
    | 'overlay';

  status:
    | 'experimental'
    | 'beta'
    | 'stable'
    | 'deprecated';

  capabilities?: readonly ComponentCapability[];

  dependencies?: ComponentDependencies;

  requirements: ComponentRequirements;
}

Capabilities describe reusable facts such as:

controlled
uncontrolled
disabled
required
invalid
loading
keyboard
focus-management
compound-api
portal
responsive

Requirements describe which engineering surfaces a component must have:

tests,
Storybook,
documentation,
accessibility evidence,
tokens,
icons,
component-specific token contracts.

The important part is what metadata does not contain.

It is not documentation prose.

It is not an implementation.

It is a compact collection of facts that tooling can make decisions from.

Different components should produce different contracts

A useful metadata model should represent real differences without creating a special schema for every component.

Consider a few examples.

Button

Button has a relatively small contract.

It supports React and React Native and has capabilities such as:

disabled
loading

It does not need the same behavioral model as an overlay or compound navigation component.

Simple components should be allowed to have simple metadata.

FormField

FormField belongs to a different architectural layer.

It is a pattern, belongs to the form category, and uses a form-control profile.

Its capabilities include things like:

disabled
required
invalid
compound-api

That tells tooling something important without forcing it to infer architecture from the name FormField.

Tabs

Tabs declares things like:

controlled
uncontrolled
keyboard
focus-management
compound-api

A checker should not need code like:

if component === "Tabs":
  remember keyboard tests

The component declares the capability once.

Modal

An overlay can declare:

controlled
uncontrolled
keyboard
focus-management
compound-api
portal

That says focus management and portal behavior belong to the component contract.

It does not try to describe the exact focus algorithm.

That remains implementation work.

This distinction is important.

Metadata should be a contract, not just configuration

A TypeScript interface is not enough.

The values themselves need validation.

Otherwise something like:

focus-managment

can silently become a new accidental capability because somebody misspelled focus-management.

So Vellira validates things such as:

supported platforms,
supported layers,
supported categories,
supported profiles,
lifecycle statuses,
capability names,
duplicate values,
dependency structure,
required engineering fields.

Invalid metadata fails before downstream tooling starts making assumptions from it.

That changes the mental model.

Metadata is not:

Here is some configuration that probably describes the component.

It is:

Here is the contract downstream tooling is allowed to trust.

One registry gives every tool the same starting point

Individual components can keep separate metadata files for reviewability.

But tooling needs one deterministic registry.

Conceptually:

Button.metadata.ts
Select.metadata.ts
Tabs.metadata.ts
Modal.metadata.ts
...
        ↓
componentMetadata registry

Consumers start from the same registry rather than independently scanning directories.

That gives us an important distinction:

Directory scanning tells you what happens to exist.

Metadata tells you what is supposed to exist.

Those are not the same question.

A half-generated component can leave files on disk.

A removed export can leave an implementation behind.

File presence alone is not enough to describe the product.

Generation should create the contract too

A source of truth is much more useful when adding a component does not require manually remembering to update it.

In Vellira, component generation includes metadata in the generation plan.

Conceptually:

component intent
      ↓
generation plan
      ↓
implementation
types
tests
stories
      ↓
Component.metadata.ts
      ↓
canonical registry

Registration needs to be deterministic too.

Repeated generation should not:

duplicate entries,
randomly reorder imports,
create unrelated diffs,
leave partially registered components.

That is why generator quality is not just about generating files.

It is about producing stable repository state.

Completeness checks become product-aware

This is where metadata starts paying for itself.

Instead of maintaining another list of known components, a completeness checker can read the canonical registry.

The metadata says:

this component supports React
this component supports React Native
tests are required
Storybook is required
docs are required
accessibility evidence is required

The checker then compares those promises with the repository.

Conceptually:

metadata
   ↓
what should exist?
   ↓
repository
   ↓
does it actually exist?

If React Native support is declared but the native implementation is missing, the result is not a reviewer eventually noticing it.

It becomes deterministic:

react-native declared
        ↓
native implementation expected
        ↓
implementation missing
        ↓
INCOMPLETE

The same pattern works for:

public exports,
tests,
stories,
docs,
accessibility surfaces,
tokens.

This removes a lot of memory work from review.

Quality checks can consume the same facts

Completeness and quality are different problems.

Completeness asks:

Are all required surfaces present?

Quality asks:

Does the implementation satisfy our engineering rules?

They should remain separate systems.

But they can share the same component facts.

A quality engine can receive:

component metadata
selected platform
repository root

and decide which checks are applicable.

A component that does not support React Native should not accidentally run native-specific checks.

A component declaring keyboard behavior can participate in keyboard-related validation without every rule maintaining its own list of component names.

That is exactly the kind of reuse metadata is good at.

Source of truth does not mean source of everything

This boundary matters a lot.

Metadata should not contain:

every public prop,
every event sequence,
CSS,
React Native styles,
complete accessibility implementation,
documentation prose,
test cases,
visual design decisions.

For example:

keyboard

in metadata means:

Keyboard behavior belongs to this component's contract.

It does not mean:

Keyboard behavior has been proven correct.

Tests and validation still need to provide that evidence.

Likewise:

docs: true

means documentation is required.

The documentation itself still belongs to the documentation system.

If metadata tries to describe every runtime detail, it eventually becomes another programming language.

At that point it stops reducing complexity and starts creating it.

Avoid component-name heuristics

This is fragile:

if component === "Tabs":
  run keyboard checks

if component === "Modal":
  expect portal behavior

if component === "FormField":
  treat as pattern

Names are product identity.

They should not become the architecture of every tool.

A stronger model asks:

Does it declare keyboard behavior?
Does it declare portal behavior?
Which layer does it belong to?
Which profile does it use?
Which platforms does it support?

That means a future component can participate in existing tooling without adding another hardcoded condition.

This is one of the biggest benefits of a reusable capability vocabulary.

Metadata turns drift into evidence

Without a canonical contract, inconsistency usually appears as a review surprise.

Someone notices:

The website says this supports native, but the package doesn't.

Or:

We forgot Storybook for this component.

Or:

This overlay has no accessibility coverage.

With metadata-driven tooling, the repository can identify the disagreement itself.

The important transformation is:

human memory
     ↓
explicit contract
     ↓
deterministic comparison
     ↓
actionable finding

The tooling is not replacing engineering judgment.

It is removing the things humans should not have to remember manually.

Keep independent systems independent

Once metadata becomes useful, there is a temptation to make everything depend directly on it.

That can create another kind of coupling.

In Vellira, the responsibilities remain separate:

component metadata
→ canonical facts

generator
→ deterministic scaffold and registration

completeness checker
→ required surface presence

quality checker
→ engineering rule evaluation

docs / website / Storybook
→ actual content and presentation

They share facts.

They do not become one giant subsystem.

That separation lets each piece evolve without turning the metadata schema into the center of every implementation decision.

Practical rules I would use elsewhere

If I were introducing component metadata into another design system, I would follow a few rules.

1. Centralize facts that are already duplicated

Do not start by designing a universal ontology.

Start with facts several systems already maintain independently.

2. Use constrained vocabularies

This:

experimental | beta | stable | deprecated

is far more useful to automation than an unrestricted status string.

3. Validate before consumption

Malformed metadata should fail before downstream tooling acts on it.

4. Keep one canonical registry

Separate files are good for review.

One deterministic registry is good for tooling.

5. Let generators register metadata automatically

If humans still need to remember registry plumbing, there is still a memory gap.

6. Let requirements drive checks

A metadata field becomes useful when something can verify it.

7. Prefer reusable capabilities over component names

Model the behavior, not a growing list of exceptions.

8. Keep evidence outside the declaration

Metadata declares expectations.

Tests, docs, and implementation provide evidence.

9. Treat schema changes like API changes

Changing the vocabulary changes what tooling is allowed to assume.

10. Stop before metadata becomes another language

If your schema starts describing every runtime branch and style decision, it has gone too far.

A source of truth is useful because reality can disagree with it

That sounds contradictory, but it is the point.

Metadata creates a stable statement:

This component supports React and React Native.

Tests are required.

Storybook is required.

Documentation is required.

Accessibility evidence is required.

These capabilities belong to its contract.

Then the repository can be compared against those statements.

When implementation, docs, exports, tests, or stories disagree with the contract, the disagreement becomes detectable.

Without the canonical statement, every downstream system has to guess.

That is why component metadata can be much more than a catalog convenience.

It becomes a compact contract between a component library and the tooling responsible for keeping that library coherent.

For Vellira, the goal is not to describe everything.

It is to describe stable facts once, validate them, and stop asking every downstream system to rediscover them.

Vellira is an open-source React and React Native design system being built in public.

One Design System, Two Runtimes: Sharing Contracts Between React and React Native

Vellira — Wed, 23 Sep 2026 08:00:00 +0000

A cross-platform design system sounds simple until the first real component forces the platforms apart.

React and React Native can expose the same product concept — a button, checkbox, input, modal — while relying on very different runtime primitives.

The web has:

DOM attributes,
anchors,
CSS,
hover,
keyboard behavior.

React Native has:

Pressable,
native accessibility props,
gesture events,
native styling.

Trying to hide all of those differences behind one implementation usually makes the abstraction worse.

In Vellira, I have been taking a different approach:

Share the semantic contract, not the runtime implementation.

That distinction has become one of the most useful architectural rules in the project.

The real goal is consistency, not identical code

When building a cross-platform component library, it is easy to treat the problem mainly as code sharing.

If a web button and a native button look similar, why not reuse as much implementation as possible?

Because developers do not primarily consume the internal component tree.

They consume the public API and its behavior.

For a Button, concepts such as these should feel familiar on both platforms:

color
appearance
size
shape
loading
disabled
fullWidth
iconOnly

A developer should be able to learn those concepts once and carry that knowledge between React and React Native.

The implementation underneath them does not need to be identical.

A more useful definition of parity is:

Cross-platform parity means shared semantics where the platforms agree, plus explicit platform-specific capabilities where they do not.

That is much more durable than forcing two different runtimes through one abstraction.

Put shared semantics in a platform-neutral contract

In Vellira, the common Button vocabulary lives in a shared type package.

A simplified version looks like this:

export type ButtonSize = 'sm' | 'md' | 'lg';

export type ButtonColor =
  | 'primary'
  | 'neutral'
  | 'success'
  | 'warning'
  | 'danger';

export type ButtonAppearance =
  | 'solid'
  | 'outline'
  | 'ghost'
  | 'soft'
  | 'link';

export interface BaseButtonProps {
  color?: ButtonColor;
  appearance?: ButtonAppearance;
  size?: ButtonSize;
  shape?: 'square' | 'rounded' | 'pill';
  fullWidth?: boolean;
  loading?: boolean;
  loadingText?: string;
  disabled?: boolean;
  iconOnly?: boolean;
}

There is nothing specifically web or native in that interface.

It describes what a Vellira Button means.

That shared layer gives both runtimes a stable semantic center.

If appearance="soft" exists on both platforms, it should represent the same design intent.

If loading disables interaction, that rule should remain consistent too.

This is where code sharing provides the most value.

Let each platform extend the contract honestly

Once the shared semantics are defined, each runtime can extend them with the capabilities developers naturally expect.

On the web, a Button can expose native HTML button behavior and anchor-related properties:

export interface ButtonProps
  extends
    BaseButtonProps,
    Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'color'>,
    Pick<
      AnchorHTMLAttributes<HTMLAnchorElement>,
      'href' | 'target' | 'rel' | 'download'
    > {
  children?: ReactNode;
  iconStart?: ReactNode;
  iconEnd?: ReactNode;
  tooltip?: string;
  badge?: ReactNode;
  shortcut?: ReactNode;
  asChild?: boolean;
}

React Native begins with the same shared contract, but its runtime surface is different:

export interface ButtonProps
  extends BaseButtonProps, Omit<PressableProps, /* exclusions */> {
  children?: ReactNode;
  iconStart?: ButtonIconElement;
  iconEnd?: ButtonIconElement;
  iconSize?: number;
  onPress?: (event: GestureResponderEvent) => void;
  style?: StyleProp<ViewStyle>;
  textStyle?: StyleProp<TextStyle>;
  accessibilityLabel?: string;
  testID?: string;
}

The two APIs clearly belong to the same design system.

But they are not artificially identical.

A web developer still gets normal web capabilities.

A React Native developer still gets normal native capabilities.

The design system owns the shared semantics without becoming an abstraction tax on either platform.

Healthy divergence is part of a good API

Some differences should not be normalized away.

A web Button can naturally behave like an anchor.

That is where href, target, or asChild make sense.

React Native does not have an HTML anchor element.

Inventing a fake href prop for native just to make the signatures look symmetrical would create parity on paper while making the API less natural.

The same is true in the other direction.

React Native has concepts such as:

StyleProp<ViewStyle>
testID
gesture events
native accessibility properties

Wrapping every one of these in invented cross-platform names would make the library harder to understand and debug.

A useful test is:

Does this property describe product-level component behavior, or the runtime that implements it?

Product-level behavior is a strong candidate for the shared contract.

Runtime behavior usually belongs to the platform package.

Share design decisions separately from implementation

Props are only one layer of cross-platform consistency.

Things like:

spacing,
radii,
typography,
colors,
interaction states

also need a common source of truth.

Those decisions can live in shared tokens while being consumed differently by CSS and React Native style objects.

The principle is the same:

Share the decision. Adapt the execution.

A shared radius token does not require CSS and React Native styling to work the same way.

It only requires both implementations to resolve the same design intent.

That prevents “cross-platform” from turning into “lowest common denominator.”

Test parity at the contract boundary

Separate implementations introduce another risk: drift.

The web Button might gain a new appearance or loading rule while React Native silently falls behind.

So parity needs explicit validation.

There are two kinds of confidence we care about:

Contract confidence — shared semantics are defined in one authoritative place.
Runtime confidence — each implementation proves that those semantics behave correctly on its own platform.

I prefer this model over a huge shared component with a growing number of platform conditionals.

A shared file can look beautifully DRY while hiding real platform-specific bugs.

Separate runtime tests make the differences visible.

A practical three-layer model

The architecture we are converging on in Vellira can be summarized in three layers.

1. Shared semantics

Define the concepts developers should learn once:

size
appearance
color
loading
disabled
shape

These belong in platform-neutral contracts.

2. Platform API

Extend the shared vocabulary with runtime-native capabilities:

Web:
href
target
DOM attributes
asChild

React Native:
onPress
accessibilityLabel
style
testID

Do not disguise real platform differences.

3. Platform implementation

Use the native tools of each runtime:

Web:
DOM + CSS

React Native:
Pressable + native styles

The implementation can diverge significantly as long as the shared semantics remain trustworthy.

This changes how we design new components

With this architecture, the first question is no longer:

How can we reuse the most code?

Instead, we ask:

What behavior is genuinely shared?
Which names should mean the same thing everywhere?
Which states need equivalent semantics?
Which capabilities are platform-specific?
What must be validated so parity cannot drift accidentally?

Only after that does implementation reuse become interesting.

Sometimes there is useful shared code below the component layer.

Sometimes two mostly independent implementations are the correct answer.

Both are fine if the public contract remains coherent.

The rule I keep coming back to

Cross-platform design systems do not need maximum code sharing.

They need maximum semantic clarity.

Developers should feel that React and React Native belong to the same system.

They should recognize:

the vocabulary,
the states,
the design decisions,
the interaction intent.

But they should not have to give up the strengths of their platform to get that consistency.

For Vellira, that means:

Share contracts aggressively. Share implementations selectively.

It is a smaller abstraction.

But it is a much more durable one.

Vellira is an open-source design system for React and React Native being built in public.

AI Can Generate More UI. Who Keeps It Consistent?

Vellira — Sat, 19 Sep 2026 16:12:38 +0000

AI can now generate UI faster than many teams can review it.

Describe a component to a coding model and, a few minutes later, you may have:

an implementation,
types,
tests,
documentation,
several variations,
and a refactor of the surrounding code.

That is a real productivity improvement.

But it changes the bottleneck.

The difficult question is becoming less:

How quickly can we create another component?

And more:

How do we keep the whole UI system coherent when humans and AI can change it this quickly?

That is one of the problems we are building Vellira around.

Generation is getting cheaper. Fragmentation is not.

Imagine an AI-generated component that looks correct, compiles, and works in isolation.

That still leaves a lot unanswered.

Does the component duplicate something that already exists?

Does its API follow the same conventions as similar components?

Does it use the same design tokens?

Does the React Native version represent the same product capability correctly?

Are accessibility expectations covered?

Were Storybook, documentation, exports, metadata, and tests updated with the implementation?

A component can be locally correct while making the system around it less consistent.

And the faster we produce UI, the faster these small differences can accumulate.

You start seeing things like:

similar components with slightly different APIs,
local colors and spacing bypassing shared tokens,
Web and React Native implementations drifting unintentionally,
accessibility behavior changing between components,
documentation falling behind the actual API,
duplicate capabilities appearing under different names,
tests encoding different expectations for equivalent behavior.

AI did not invent these problems.

It increases the rate at which they can appear.

A component library is necessary, but it is not enough

A traditional design system gives you components, tokens, guidelines, and documentation.

Those are still essential.

But a catalog can tell you that Button, Select, or Tabs exists.

It cannot automatically answer:

whether a new implementation should exist at all,
whether it follows the established API model,
whether its platform differences are intentional,
whether its documentation still matches the code,
whether it satisfies the same quality expectations as the rest of the system.

This becomes especially important when developers and coding agents work in the same repository.

A coding model can produce perfectly reasonable code that does not quite belong to the system around it.

The question becomes bigger than:

Does this component work?

It becomes:

Does this change still belong to the same product and engineering system?

The system around generation becomes more important

Coding models are getting better quickly.

We should assume they will become better at:

implementing components,
modifying large codebases,
writing tests,
refactoring APIs,
generating documentation,
making coordinated multi-file changes.

That is good.

The goal should not be to slow them down.

But faster production means the repository needs stronger boundaries.

If an agent changes ten components in one pass, the project still needs to know whether:

their APIs remain coherent,
accessibility behavior remains correct,
public exports remain synchronized,
documentation still reflects reality,
design tokens are still authoritative,
React and React Native only diverge where they are supposed to.

The better generation becomes, the more useful explicit and deterministic project contracts become.

What we are building into Vellira

Vellira started as a cross-platform design system for React and React Native.

The foundation is still familiar:

reusable components,
shared design tokens,
Storybook,
documentation,
platform-specific implementations behind shared product intent.

But while building the component catalog, another requirement became obvious.

Creating the component is only one stage of its lifecycle.

A production component also needs:

metadata,
public types,
exports,
tests,
accessibility coverage,
Storybook examples,
website documentation,
platform validation,
completeness checks,
quality checks.

So we started making those expectations machine-readable and repeatable.

For example, instead of asking a reviewer to remember every required artifact, the project can check whether a component has the expected implementation, tests, documentation, metadata, exports, and platform support.

Instead of treating component creation as:

generate file → done

we are moving toward something closer to:

intent
  ↓
component production
  ↓
implementation
  ↓
tests / accessibility / metadata / docs
  ↓
quality and completeness validation
  ↓
review
  ↓
canonical component

The important part is not any single checker or generator.

It is that the lifecycle becomes explicit.

The author matters less than the resulting state

I do not think AI-generated code needs to live in a completely separate category.

A human can introduce an inconsistent API.

A coding agent can follow an existing convention perfectly.

A developer can forget to update documentation.

Automation can keep it synchronized.

Once code enters the repository, the important question is not who typed it.

The important question is whether the resulting state of the project is valid.

That is why we are more interested in lifecycle tooling than in trying to distinguish “human code” from “AI code.”

Both humans and AI benefit when more of the consistency burden belongs to the system itself.

Cross-platform UI makes this harder

Vellira targets both React and React Native.

And “the same component” does not necessarily mean “the same implementation.”

Web and native platforms have different:

primitives,
accessibility APIs,
keyboard and focus models,
interaction patterns,
layout constraints.

Some behavior should be shared.

Some behavior should intentionally diverge.

So a good cross-platform system cannot simply copy the Web implementation into React Native and call that consistency.

It needs to preserve the same product intent while allowing each runtime to behave appropriately.

AI can generate both implementations quickly.

The harder problem is determining whether those implementations still represent one coherent component.

The bottleneck is moving toward coordination

This is probably the most interesting consequence of AI-assisted frontend development.

When producing UI becomes cheaper, teams can produce more of it.

More experiments.

More parallel changes.

More automated contributions.

More components.

The limiting resource moves away from typing speed.

It moves toward:

coordination,
consistency,
review,
maintenance.

That changes what useful developer tooling looks like.

If ten UI changes can be produced in the time it previously took to produce one, tooling that helps those ten changes remain part of the same system becomes much more valuable.

That is the direction we are exploring with Vellira:

AI can generate more UI. Vellira is being built to help keep that UI coherent.

Where Vellira is today

We are still proving this inside Vellira itself.

The immediate work is concrete:

grow the React and React Native component catalog,
make component production more repeatable,
strengthen accessibility and quality validation,
improve documentation,
make the public project easier to install and use.

We are deliberately making these workflows reliable inside one real design system before claiming that they can manage arbitrary external repositories.

But the direction is clear.

Frontend teams are going to work with more generated code, not less.

The answer should not be to make generation slower.

It should be to make the system around generation stronger.

Vellira is an open-source React and React Native design system being built in public.

DEV Community: Vellira

From Scaffold to Production: How Vellira Generates Components

Component.tsx is only one node

Start with explicit intent

Profiles beat component-name heuristics

Plan React and React Native together, generate them separately

Generate the surrounding product surface

Public exports should not depend on memory

Generate test requirements, not empty test files

Regeneration needs ownership boundaries

Fail before writing

--dry-run is a safety feature

Idempotency is part of the contract

Downstream generators should still have boundaries

What the generator should not decide

Fix systemic gaps once

The generator is not primarily a typing shortcut

Why We Built Quality Gates Before Growing to 20 Components

Component count is a misleading progress metric

A green build proves less than it feels like it proves

Completeness and quality are different questions

Completeness: is the whole component actually there?

Quality: does the evidence support the claim?

Storybook is a product surface too

Documentation can drift independently of code

Public APIs deserve their own checks

Cross-platform components need independent evidence

Overlays expose weak parity very quickly

Small deterministic checks compose better

Structured findings are more useful than log text

Automate memory, not engineering judgment

Fix repeated failures at the system level

Why a bounded target like 20 components helps

Quality gates are cheapest before you desperately need them

The goal is cheaper trust

Component Metadata as a Source of Truth for a Design System

The hidden cost of five component lists

What belongs in component metadata?

Different components should produce different contracts

Button

FormField

Tabs

Modal

Metadata should be a contract, not just configuration

One registry gives every tool the same starting point

Generation should create the contract too

Completeness checks become product-aware

Quality checks can consume the same facts

Source of truth does not mean source of everything

Avoid component-name heuristics

Metadata turns drift into evidence

Keep independent systems independent

Practical rules I would use elsewhere

1. Centralize facts that are already duplicated

2. Use constrained vocabularies

3. Validate before consumption

4. Keep one canonical registry

5. Let generators register metadata automatically

6. Let requirements drive checks

7. Prefer reusable capabilities over component names

8. Keep evidence outside the declaration

9. Treat schema changes like API changes

10. Stop before metadata becomes another language

A source of truth is useful because reality can disagree with it

One Design System, Two Runtimes: Sharing Contracts Between React and React Native

The real goal is consistency, not identical code

Put shared semantics in a platform-neutral contract

Let each platform extend the contract honestly

Healthy divergence is part of a good API

Share design decisions separately from implementation

Test parity at the contract boundary

A practical three-layer model

1. Shared semantics

2. Platform API

3. Platform implementation

This changes how we design new components

The rule I keep coming back to

AI Can Generate More UI. Who Keeps It Consistent?

Generation is getting cheaper. Fragmentation is not.

A component library is necessary, but it is not enough

`Component.tsx` is only one node

`--dry-run` is a safety feature