@economic/taco
UI React component library
Usage
import { Button } from '@economic/taco';
const MyComponent = () => <Button>Guacamole</Button>;
Installation
npm install --save @economic/taco
Peer Dependencies
| Package | Version |
|---|---|
react | ^18.3.1 |
react-dom | ^18.3.1 |
tailwindcss | >=3.4.19 |
Styling
Taco ships a pre-compiled CSS file (dist/taco.css) that contains its component styles. However, consumers still need their own Tailwind setup to use the design system's theme tokens and utility classes in their application code.
Browser targeting, purging and minification should be performed by you, the consumer.
Your tailwind.config.js should use the taco config as a preset:
module.exports = {
presets: [require('@economic/taco/tailwind.config.js')],
content: {
files: ['./src/**/*.{ts,tsx}', './node_modules/@economic/taco/dist/**/*.js'],
},
};
Then import the Tailwind layers and the taco stylesheet in your application CSS:
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import '@economic/taco/taco.css';
@import 'tailwindcss/utilities';
PostCSS Configuration
Important: This design system requires postcss-import to function properly.
The CSS imports above use @import statements instead of the @tailwind directive because of the postcss-import plugin. This is necessary to avoid issues when importing additional CSS files.
Your PostCSS config should look something like this:
module.exports = {
plugins: ['postcss-import', 'tailwindcss', 'autoprefixer'],
};
Development
Prerequisites
- Node
>=24(managed via Volta, see rootpackage.json) - This package lives in a monorepo alongside
@economic/taco-tokens. Always runnpm installfrom the repository root.
Getting Started
# from the repository root
npm install
npm run dev # starts Storybook on http://localhost:6006
Available Scripts
Run these from the package directory (packages/taco):
| Script | Description |
|---|---|
npm run build | Type-check with tsc then build the library with Vite |
npm test | Run unit tests with Vitest |
npm run lint | Run stylelint on CSS files and oxlint on JS/TS files |
npm run e2e | Run Playwright end-to-end tests |
npm run generate-icons | Regenerate icon components from SVG sources |
Or from the repository root:
| Script | Description |
|---|---|
npm run dev | Start Storybook on port 6006 |
npm run build | Build all packages |
npm run lint:styles | Run stylelint for @economic/taco (src/**/*.css) |
npm run lint:classes | Run the class-linter on all TSX/TS source files |
Storybook
Storybook is the primary development and documentation environment. Run npm run dev from the repository root to start it. Component stories and documentation live alongside their implementations in __stories__/ folders.
Guidelines for New Components
Create a folder under src/components/ with the name of the component, e.g. <NewComponent />:
src/components/
├── NewComponent/
│ ├── __stories__/
│ │ ├── NewComponent.dev.stories.tsx
│ │ ├── NewComponent.mdx
│ │ └── NewComponent.stories.tsx
│ ├── NewComponent.css
│ ├── NewComponent.spec.tsx
│ ├── NewComponent.e2e.ts
│ └── NewComponent.tsx
The component's style, implementation, tests, and documentation are co-located in its own folder.
| File | Purpose |
|---|---|
__stories__/NewComponent.mdx | Component documentation |
__stories__/NewComponent.dev.stories.tsx | Development stories for Storybook |
__stories__/NewComponent.stories.tsx | Stories used in documentation |
NewComponent.css | Component styles, directly imported in the implementation |
NewComponent.spec.tsx | Unit tests (Vitest) |
NewComponent.e2e.ts | End-to-end tests (Playwright), if applicable |
NewComponent.tsx | Component implementation |
Linting
Three linting layers run across the codebase:
| Tool | Scope | Description |
|---|---|---|
| oxlint | JS/TS files | General code quality linting |
| stylelint | CSS files (src/**/*.css) | Encourages approved design tokens |
| class-linter | TSX/TS files | Flags disallowed class usage (local oxlint JS plugin) |
Stylelint and the class-linter also run as pre-commit hooks via nano-staged.
The design-token rules for both stylelint and oxlint come from
@economic/taco-rules, so CSS and TSX accept the
same classes. taco's configs (stylelint.config.mjs, .oxlintrc.json,
.oxlintrc.classes.json) extend its shipped configs and only override single
rules. CSS and TS/TSX are switched separately: stylelint.config.mjs for CSS,
both .oxlintrc.json and .oxlintrc.classes.json for TS/TSX.
Testing
- Unit tests use Vitest with
@testing-library/react. Test files follow the*.spec.tsxconvention. - End-to-end tests use Playwright. Test files follow the
*.e2e.tsconvention.