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.
Formwires 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.Cardtakes 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.mdxis the "when to use" guide with live demos. - Names carry intent. A
.style.tsfile is always the styled layer; a.interface.tsfile 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 validatebefore you push; thepre-pushhook enforces it, including the MDX compile and the docs-parity test. - A consumer-visible change without a changeset → add one with
yarn changeset.