Pine Design System — Agent Instructions

Project Overview

Stencil.js web component library in an Nx monorepo. Core components live in libs/core/src/components/.

All components are prefixed with pds- (e.g., pds-button, pds-table)
Each component may include: *.tsx, *.scss, *.figma.ts, stories/, docs/, test/, and auto-generated readme.md
Composite components have nested subcomponent directories (e.g., pds-table/pds-table-row/)
React wrappers are generated in libs/react/
Generate new components: npm run stencil.generate pds-[name] — choose *.scss Format, then copy stories/ and docs/ from an existing component

Use Stencil decorators: @Component, @Prop, @State, @Event, @Listen, @Method, @Watch
Props should have JSDoc comments — these generate the auto-docs in readme.md
Use @Event() with EventEmitter for custom events; prefix with pds (e.g., pdsTableRowSelected)
Shadow DOM is used — style with ::part() attributes and :host selectors
readme.md is auto-generated by Stencil — do not edit manually

JSDoc descriptions on @Prop, @Event, and @Method must use consistent terminology across components — review similar props/events on other components before writing new descriptions
When adding a prop or event that exists in a similar form on another component, match the wording and phrasing of the existing description
MDX docs in the component's docs/ folder — include live examples with <Canvas> and <Story>
Storybook stories in the component's stories/ folder — export a default meta + named story exports

Lefthook enforces commitlint, validate-branch-name, and lint-staged — never skip hooks
Branch names: {type}/{description} — do NOT include ticket or issue numbers
Accepted branch types: chore, ci, docs, feat, fix, hotfix, perf, refactor, revert, style, test
Commit scope = component name (e.g., feat(pds-table):, fix(pds-button):), single line, no ticket numbers
Commit type by file:
- feat(component): — new props, events, methods, or component behavior in *.tsx
- fix(component): — bug fixes in component code
- test(component): — test files (*.spec.tsx, *.e2e.ts)
- docs(component): — MDX docs, Storybook stories, and documentation updates
- style(component): — SCSS/CSS-only changes
- refactor(component): — code restructuring with no behavior change
- chore: — tooling, config, dependencies
PR titles: type(scope): description — use the template at .github/pull_request_template.md
If your branch is behind main, rebase before pushing — requires at least two approved reviews before merging
See CONTRIBUTING.md for full contributor guidelines

Spec tests go in the component's test/ folder (e.g., pds-chip/test/pds-chip.spec.tsx) using Stencil's newSpecPage
E2E tests also in the component's test/ folder using Stencil's newE2EPage
Every new prop, event, or behavior needs corresponding test coverage

Build all: npm run build.all
Test all: npm run test.all
Lint all: npm run lint.all
Target core only: npx nx run @pine-ds/core:build, npx nx run @pine-ds/core:test
After modifying *.tsx, rebuild to regenerate components.d.ts and readme.md
Dev server: npm run start (Storybook at localhost:6006)
Linting: ESLint (@stencil-community/recommended + @typescript-eslint), Prettier, and Stylelint

Always: follow existing component patterns, run lint and tests before committing, use conventional commits with component scope, match JSDoc terminology from similar components
Ask first: adding new dependencies, creating files outside component directories, making breaking API changes (removing props/events), modifying CI/CD or build config
Never: skip lefthook hooks, edit auto-generated files (readme.md, components.d.ts) manually, commit secrets or .env files, modify node_modules/ or dist/