| name | seldon |
| description | Phillips Seldon design system — React components in src/components and src/patterns, co-located Storybook and Vitest, SCSS with $px BEM prefix. Use for library work, Agent Review on UI components, and code review in this repo. Canonical project rules live here plus AGENTS.md and docs/agents/*. |
Seldon design system
This repository is @phillips/seldon, a published component library—not a
Remix/React Router application. There are no app/routes, SSR entrypoints, or
product API clients here.
What ships from this repo
- Components:
src/components/<Name>/ — each primary UI module co-located
with *.stories.tsx, *.test.tsx, and _name.scss as applicable.
- Patterns:
src/patterns/<Name>/ — composed layouts/widgets using the same
co-location rules where the team adds stories/tests.
- Build:
npm run build produces dist/ for npm consumers.
- Docs in Storybook:
npm start (Storybook on port 6006).
New component workflow
- Run scaffold script if applicable (
npm run create-component) or replicate an existing folder (Button is a minimal pattern; Carousel for compound components).
- Implement component using
forwardRef, call getCommonProps(props, 'ComponentName') early.
- Create
Component.stories.tsx with Overview + variations (match tone of existing stories).
- Write tests hitting rendering, variant/branch logic, keyboard/focus if interactive.
- Add SCSS partial
_component.scss using the seldon- prefixed base class.
- Export from folder
index.ts and root src/index.ts.
- Run:
npm run lint && npm test && npm run build before committing.
- Validate accessibility by checking the component in Storybook under the Accessibility tab and fix any issues.
Styling and DOM conventions
- TSX: use
getCommonProps / px from src/utils/index.tsx the same
way neighboring components do (getCommonProps sets className and
data-testid stems; px is the seldon namespace string).
- SCSS:
@use '~scss/allPartials' as *; (or the documented relative path to
partials). Prefix BEM blocks with .#{$px}-... where $px is defined in
shared vars (src/scss/_vars.scss — currently seldon).
- Prefer existing primitives (
Text, Button, Grid, etc.) before adding
parallel patterns.
- Do not use the mixin for
@include text(variant) in the SCSS files, instead use the component.
Testing
- Unit / component: Vitest + Testing Library; tests live next to components
(
*.test.tsx). Shared helpers: src/utils/testUtils.tsx.
- Storybook:
*.stories.tsx co-located; Chromatic runs in CI (npm run chromatic with STORYBOOK=1).
Related skills (optional depth)
.agents/skills/web-component-design/SKILL.md — broader component-library
patterns..agents/skills/vercel-composition-patterns/SKILL.md — compound
components, variants, context..agents/skills/vercel-react-best-practices/SKILL.md — performance; see
the “Scope in this repository” section there (skip server-only rules for
typical library work)..agents/skills/branch-coverage-hotspot-hunter/SKILL.md — flag branch coverage hotspots..agents/skills/storybook-coverage-checker/SKILL.md — flag storybook coverage gaps..agents/skills/accessibility-compliance-accessibility-audit/SKILL.md — flag accessibility compliance issues..agents/skills/security-compliance-security-audit/SKILL.md — flag security compliance issues..agents/skills/performance-compliance-performance-audit/SKILL.md — flag performance compliance issues..agents/skills/best-practices-best-practices-audit/SKILL.md — flag best practices issues..agents/skills/code-style-code-style-audit/SKILL.md — flag code style issues..agents/skills/documentation-documentation-audit/SKILL.md — flag documentation issues..agents/skills/testing-testing-audit/SKILL.md — flag testing issues.
Repo docs (read in order)
AGENTS.md — high-level map and non-negotiables.docs/agents/CONVENTIONS.md — TypeScript, React, SCSS, tests.docs/agents/QUALITY.md — checks and coverage expectations.docs/agents/ARCHITECTURE.md — directory layout.
After substantive edits, run npm run format (Prettier) before commit.
