Skip to main content

Component best practices

Conventions and rules for building Zeta components. Read this before writing any component code.

Fundamentals​

Non-negotiable

Every component must follow every rule in this section. A PR that violates any of them will not be merged.

Design comes first​

No component work starts without a finalised Figma design. If a design does not exist, or is still in draft/review, stop and get it signed off before writing any code.

The component's props, variants, slots, sizes, and states are derived directly from the Figma file. Implementing ahead of design creates rework and API churn.

The implementation must match the Figma design exactly: every variant, every size, every state (default, hover, focus, disabled, error, etc.). Do not add props, colours, or behaviour that are not in the design. Do not omit props, colours, or behaviour that are.

PR checklist​

Run through every item in the relevant section before requesting review.

Design​

  • Figma design is finalised and signed off
  • All variants, sizes, and interactive states implemented — nothing added, nothing missing
  • All dimensions, spacing, and colours come from design tokens — no hardcoded values
  • Figma link in the component source points to the specific node

Workflow​

  • Jira ticket exists and is linked in the PR description
  • Branch name references the Jira ticket key
  • PR title follows Conventional Commits format
  • Breaking changes discussed with the team and flagged in the commit footer

Language rules​

  • No escape hatches (any / dynamic) anywhere in the component
  • All properties and method signatures have explicit types
  • Build / compile — zero errors

Atomic design​

  • No existing atom reimplemented — ZetaIcon, ZetaBadge, zeta-icon, zeta-badge, etc. are imported and used
  • Atom has no upward dependencies on molecules or organisms

Component structure​

  • Component file exists in the correct location
  • Class/tag name follows naming conventions
  • All required metadata present (dart doc / JSDoc with Figma + Storybook/Widgetbook links)
  • Export added alphabetically to the package index

Design tokens​

  • No hardcoded colour, spacing, radius, elevation, or typography values
  • Only semantic tokens used — not primitive tokens

Tests​

  • Test file exists
  • All test groups present
  • Accessibility tests pass across all variants and theme modes
  • Full test suite — zero failures

Documentation​

  • Storybook story / Widgetbook use case file exists
  • Every prop/parameter exposed as a control/knob
  • Figma design panel link set
  • Documentation tool regenerated (manifest / build_runner)