Skip to the content

Repository Layout

Every component in @apollion-dsi/core owns one folder with the same six files. Read the folder shape first: every other contributor page assumes it.
Contributing

The rule

A component lives in packages/core/src/<group>/<Component>/ and ships these files together, in the same pull request:

Button/
├── Button.tsx            # the component, with TSDoc
├── Button.interface.ts   # public prop types, TSDoc per prop
├── Button.style.ts       # styled-components built from the factories
├── Button.story.tsx      # Storybook stories
├── Button.test.tsx       # Jest tests and style snapshots
└── README.mdx            # the page this site renders

Button is the reference: when a pattern is unclear, copy what Button does.

How it works

  • Zero business logic. Components are visual. No data fetching, no domain formatting, no validation beyond what the DOM enforces. Form wires react-hook-form and zod, but the schema and submit handler are yours.
  • Composition over configuration. Complex UI composes small primitives: Table → TableRow → TableCell, Form → Field → Input. Card takes named slots instead of relying on child order.
  • Three documentation layers. TSDoc is the technical reference and feeds the props tables. Storybook is the interactive playground. README.mdx is the "when to use" guide with live demos.
  • Names carry intent. A .style.ts file is always the styled layer; a .interface.ts file is always the public prop contract. Comments explain why, not what.

Pitfalls

  • A change to a component without its README, story or test → update all six files in the same change.
  • Trusting CI to catch documentation drift → CI runs only on demand. Run yarn validate before you push; the pre-push hook enforces it, including the MDX compile and the docs-parity test.
  • A consumer-visible change without a changeset → add one with yarn changeset.

See also