Add MIT license, README, and CLAUDE.md
Adds project documentation: MIT license file, README with package overview/usage/development guide, and CLAUDE.md with maintenance guidelines covering feature parity, testing strategy, and CI. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
michael
100
CLAUDE.md
Normal file
100
CLAUDE.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# CLAUDE.md — DT Design System
|
||||
|
||||
## Project Overview
|
||||
|
||||
Monorepo for the Dangerous Things design system. Three npm packages publish under `@dangerousthings/*`:
|
||||
|
||||
- **tokens** — canonical design tokens in TypeScript, compiled to JS and auto-generated as CSS custom properties
|
||||
- **web** — CSS themes (bevels, glows, elevation, forms) consumed by web apps
|
||||
- **react-native** — React Native components built on React Native Paper
|
||||
|
||||
Three brand themes: **dt** (neon cyberpunk / beveled), **classic** (dark navy / magenta), **supra** (MD3 / blue).
|
||||
|
||||
## Build & Tooling
|
||||
|
||||
- **Turbo** orchestrates builds; `packages/tokens` must build first (dependency for web and react-native).
|
||||
- Build everything: `npm run build`
|
||||
- Typecheck everything: `npm run typecheck`
|
||||
- Tokens build: `tsc` then `node dist/scripts/generate-css.js`
|
||||
- Web build: `node scripts/build.js` (copies CSS, assembles brand token CSS, copies fonts)
|
||||
- React Native build: `tsc`
|
||||
- Versioning: Changesets (`npx changeset`, `npm run version-packages`, `npm run release`)
|
||||
|
||||
## Architecture Rules
|
||||
|
||||
- Tokens are the single source of truth. Never hard-code color, typography, or shape values in web or react-native packages — always reference the tokens package.
|
||||
- Web package is pure CSS — no JavaScript runtime except the optional `theme-registry` module.
|
||||
- React Native components wrap React Native Paper and must list it (and react, react-native, react-native-svg, react-native-safe-area-context) as peer dependencies, never bundled dependencies.
|
||||
|
||||
## Feature Parity
|
||||
|
||||
When adding or modifying a design token, component, or visual behavior, keep all three layers in sync:
|
||||
|
||||
1. **Tokens** — add/update the value in every brand file (`packages/tokens/src/brands/{dt,classic,supra}.ts`) and in the shared type (`packages/tokens/src/types.ts`).
|
||||
2. **Web** — if the token maps to a CSS component, update the relevant CSS file under `packages/web/src/components/`. Ensure the CSS custom property name matches the token path (e.g., `--dt-color-brand-primary`).
|
||||
3. **React Native** — update the corresponding component(s) under `packages/react-native/src/components/` and ensure the theme provider maps the new token.
|
||||
|
||||
### Parity Checklist (use before closing any PR)
|
||||
|
||||
- [ ] New tokens exist in all three brand files with correct values
|
||||
- [ ] Token types are updated if the shape of the token object changed
|
||||
- [ ] CSS generation script produces the expected custom properties (`npm run build:tokens` then inspect `dist/css/`)
|
||||
- [ ] Web CSS files reference the new/changed custom properties
|
||||
- [ ] React Native components consume the new tokens via the theme
|
||||
- [ ] All three packages build cleanly (`npm run build`)
|
||||
- [ ] TypeScript typechecks pass (`npm run typecheck`)
|
||||
|
||||
## Testing
|
||||
|
||||
> No test framework is configured yet. When adding tests, follow the guidance below.
|
||||
|
||||
### Strategy
|
||||
|
||||
- **Tokens**: unit tests for token value correctness and CSS generation output. Verify every brand file satisfies the shared type. Snapshot the generated CSS files.
|
||||
- **Web**: visual regression tests or snapshot tests for the compiled CSS. Ensure each brand's generated stylesheet contains expected custom properties.
|
||||
- **React Native**: component rendering tests with React Native Testing Library. Test that each component renders without errors under every brand theme. Test interactive behaviors (press, toggle, expand).
|
||||
|
||||
### Conventions (apply once a framework is added)
|
||||
|
||||
- Place test files next to source: `foo.ts` → `foo.test.ts`, `DTButton.tsx` → `DTButton.test.tsx`.
|
||||
- Name test blocks clearly: `describe("DTButton")`, `it("renders in contained mode")`.
|
||||
- Run tests via Turbo: add a `test` task to `turbo.json` and per-package `test` scripts.
|
||||
- CI should run `turbo run test` alongside `build` and `typecheck`.
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Adding a New Component
|
||||
|
||||
1. Create the React Native component in `packages/react-native/src/components/DTFoo.tsx`.
|
||||
2. Re-export it from `packages/react-native/src/index.ts`.
|
||||
3. If it needs new tokens, add them to all brand files and types first.
|
||||
4. If there is a web equivalent (CSS-only), add a CSS file in `packages/web/src/components/`.
|
||||
5. Create a changeset: `npx changeset` — select affected packages and describe the change.
|
||||
|
||||
### Adding a New Brand
|
||||
|
||||
1. Create `packages/tokens/src/brands/newbrand.ts` implementing the full `BrandTokens` type.
|
||||
2. Re-export it from `packages/tokens/src/index.ts`.
|
||||
3. The CSS generation script will pick it up automatically.
|
||||
4. Add the brand to the React Native `DTThemeProvider` brand union.
|
||||
5. Update this file and the README.
|
||||
|
||||
### Modifying Tokens
|
||||
|
||||
- Always start in `packages/tokens/src/types.ts` if the token shape changes.
|
||||
- Update every brand file — the TypeScript compiler will flag missing properties.
|
||||
- Rebuild tokens (`npm run build:tokens`) and verify the generated CSS before touching downstream packages.
|
||||
|
||||
### CI
|
||||
|
||||
GitHub Actions runs on push to `main` and on PRs:
|
||||
- Builds across Node 18, 20, 22
|
||||
- Runs typecheck
|
||||
- Validates changesets on PRs (`npx changeset status`)
|
||||
|
||||
### Code Style
|
||||
|
||||
- TypeScript strict mode.
|
||||
- CSS uses BEM-ish class names prefixed with `dt-` (e.g., `.dt-bevel-card`).
|
||||
- React Native components are prefixed `DT` (e.g., `DTButton`).
|
||||
- Keep files focused — one component per file, one brand per file.
|
||||
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2025 Dangerous Things
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
126
README.md
Normal file
126
README.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# DT Design System
|
||||
|
||||
Shared design tokens, web CSS, and React Native components for the Dangerous Things product family.
|
||||
|
||||
## Packages
|
||||
|
||||
| Package | Description |
|
||||
|---------|-------------|
|
||||
| [`@dangerousthings/tokens`](packages/tokens) | Canonical design tokens (colors, typography, shape) defined in TypeScript and exported as CSS custom properties |
|
||||
| [`@dangerousthings/web`](packages/web) | Web CSS themes — bevels, glows, elevation, and form styles |
|
||||
| [`@dangerousthings/react-native`](packages/react-native) | React Native components built on React Native Paper |
|
||||
|
||||
## Brand Themes
|
||||
|
||||
Three brand themes ship out of the box:
|
||||
|
||||
- **DT** — neon cyberpunk aesthetic with beveled corners and glow effects (Tektur font)
|
||||
- **Classic** — dark navy palette with magenta accents and standard border radius
|
||||
- **Supra** — Material Design 3–inspired with blue accent and rounded corners
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js >= 18
|
||||
- npm >= 10
|
||||
|
||||
### Install & Build
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build # builds all packages via Turbo
|
||||
```
|
||||
|
||||
### Per-Package Builds
|
||||
|
||||
```bash
|
||||
npm run build:tokens
|
||||
npm run build:web
|
||||
npm run build:react-native
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Web (CSS)
|
||||
|
||||
```css
|
||||
@import "@dangerousthings/web"; /* base index */
|
||||
@import "@dangerousthings/web/tokens/dt.css"; /* DT brand tokens */
|
||||
@import "@dangerousthings/web/components/bevels.css";
|
||||
```
|
||||
|
||||
### React Native
|
||||
|
||||
```tsx
|
||||
import { DTThemeProvider } from "@dangerousthings/react-native";
|
||||
import { DTButton, DTCard } from "@dangerousthings/react-native";
|
||||
|
||||
export default function App() {
|
||||
return (
|
||||
<DTThemeProvider brand="dt">
|
||||
<DTCard>
|
||||
<DTButton mode="contained" onPress={() => {}}>
|
||||
Press Me
|
||||
</DTButton>
|
||||
</DTCard>
|
||||
</DTThemeProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Tokens (JavaScript/TypeScript)
|
||||
|
||||
```ts
|
||||
import { dt } from "@dangerousthings/tokens/brands/dt";
|
||||
console.log(dt.color.brand.primary); // "#00ffff"
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Scripts
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `npm run build` | Build all packages (Turbo) |
|
||||
| `npm run clean` | Remove all `dist/` directories |
|
||||
| `npm run typecheck` | Run TypeScript type checking |
|
||||
| `npm run lint` | Lint all packages |
|
||||
|
||||
### Release
|
||||
|
||||
This project uses [Changesets](https://github.com/changesets/changesets) for versioning.
|
||||
|
||||
```bash
|
||||
npx changeset # create a new changeset
|
||||
npm run version-packages # bump versions from pending changesets
|
||||
npm run release # build + publish to npm
|
||||
```
|
||||
|
||||
## React Native Components
|
||||
|
||||
DTAccordion, DTButton, DTCard, DTCheckbox, DTChip, DTDrawer, DTGallery, DTHexagon, DTLabel, DTMediaFrame, DTMenu, DTModal, DTProgressBar, DTQuantityStepper, DTRadioGroup, DTSearchInput, DTSwitch, DTTextInput
|
||||
|
||||
## Web CSS Modules
|
||||
|
||||
- `bevels.css` — angular clip-path patterns for the DT brand
|
||||
- `glows.css` — neon drop-shadow effects for clipped elements
|
||||
- `forms-dt.css` — text inputs, checkboxes, radio buttons, switches
|
||||
- `elevation.css` — shadow elevation for Supra / MD3 brand
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
dt-design-system/
|
||||
├── packages/
|
||||
│ ├── tokens/ # Design token definitions + CSS generation
|
||||
│ ├── web/ # CSS themes and components
|
||||
│ ├── react-native/ # React Native Paper components
|
||||
│ └── showcase/ # Demo app (placeholder)
|
||||
├── turbo.json # Turbo pipeline config
|
||||
└── package.json # Workspace root
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE)
|
||||
Reference in New Issue
Block a user