Contributing

Nasaq is developed in the open at github.com/fadymondy/nasaq. Bug reports, fixes, accessibility findings and new components are welcome. For anything larger than a fix, open an issue first so the shape can be agreed before you invest the time.

Set upCopy Anchor Link

You need Node 22 or newer and pnpm 11.

git clone https://github.com/fadymondy/nasaq.git
cd nasaq
pnpm install
pnpm lab            # this Storybook, on http://localhost:6106

The checksCopy Anchor Link

CI runs these, and so should you before opening a pull request:

pnpm typecheck          # TypeScript across every package
pnpm lint               # logical properties only, no raw hex colours
pnpm test               # includes the token contrast matrix
pnpm check:components   # every component has a valid README and a story
pnpm --filter @nasaq/site registry   # build and validate the shadcn registry

Layout of the repoCopy Anchor Link

Adding or changing a componentCopy Anchor Link

1. Create packages/web/src/components/<name>/ with <name>.tsx and an index.ts that re-exports it. Build on a Base UI primitive when one exists.
2. Write its manual, README.md, in the format in docs/COMPONENT-README.md: frontmatter, when to use it, API tables, accessibility, RTL notes. The manual feeds the docs tab, the registry and the MCP server, so it has to match the code.
3. Write its story in apps/lab/stories/. The story id is the lowercased title with spaces and slashes turned into dashes, and the README's story: field must point at it. Cover the states and an Arabic story.
4. Export it from packages/web/src/index.ts.
5. Run the checks above.

House rulesCopy Anchor Link

• Logical properties only. ms-*, pe-*, text-start, start-0, border-s, rounded-s. Never ml-, pr-, left-, text-left. In comments say "context-click", not the physical mouse-button word, because lint scans them.
• Tokens, not colours. No raw hex in components. If a token is missing, add it to packages/tokens/src/dtcg and rebuild.
• Direction-safe. Directional icons go through Icon; user text of unknown direction goes through Bdi or BidiText.
• Accessible by default. Keyboard operable, visible focus, labelled, no colour-only state. The lab runs axe on every story.
• No new runtime dependencies in packages/web without discussing it first.
• Official brand marks are never recoloured, mirrored or redrawn. Use ProductMark.
• Do not add font files, logos or images you do not have the right to redistribute.

Commits and releasesCopy Anchor Link

Use short, imperative commit messages. Releases are managed with Changesets: a change that affects a published package needs a changeset (pnpm changeset), which says which packages change and whether it is a patch, minor or major. See Changelog and versioning.

SecurityCopy Anchor Link

Please do not open public issues for vulnerabilities. Follow the policy in SECURITY.md in the repository.

LicenceCopy Anchor Link

By contributing you agree that your contribution is released under the project's MIT licence.