{"_id":"@arpit194/themeforge","_rev":"2-a27ae14bf55bb6d470218bcd8b836755","name":"@arpit194/themeforge","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.1":{"name":"@arpit194/themeforge","version":"0.1.1","_id":"@arpit194/themeforge@0.1.1","maintainers":[{"name":"arpit194","email":"arpit.patel194@gmail.com"}],"dist":{"shasum":"993cb98ea9ad9b832ac673ce04610ffb34a0fc9d","tarball":"https://registry.npmjs.org/@arpit194/themeforge/-/themeforge-0.1.1.tgz","fileCount":17,"integrity":"sha512-LgVWD4efEq2T4DlcZ5pVJSAcQuFBE4BdwLy0toJTQGkRqAurqiur1lL6G437AjegKMN8JujOWQNd74aOLD63oQ==","signatures":[{"sig":"MEUCIQDJrj1N3/ivE2bBMJTUXTEnlkj8GWToJCo7AMbxlGVrdAIgXLQ31O5ThTz2SnqYcm4TPGGpUlVT1m2QurbPlSZMh8c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73347},"type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d737a238ff9e959da743d27fae7f43ec1db75690","scripts":{"dev":"vite build --watch","lint":"eslint .","build":"npm run typecheck && vite build","analyze":"ANALYZE=true vite build","preview":"vite preview","typecheck":"tsc --noEmit","release:major":"npm version major && git push && git push --tags","release:minor":"npm version minor && git push && git push --tags","release:patch":"npm version patch && git push && git push --tags"},"_npmUser":{"name":"arpit194","email":"arpit.patel194@gmail.com"},"_npmVersion":"10.8.2","description":"A lightweight, type-safe design token library for React","directories":{},"sideEffects":false,"_nodeVersion":"20.20.1","_hasShrinkwrap":false,"devDependencies":{"vite":"^8.0.1","react":"^19.2.4","eslint":"^9.39.4","globals":"^17.4.0","react-dom":"^19.2.4","@eslint/js":"^9.39.4","typescript":"~5.9.3","@types/node":"^24.12.0","@types/react":"^19.2.14","vite-plugin-dts":"^4.5.4","@types/react-dom":"^19.2.3","typescript-eslint":"^8.57.0","@vitejs/plugin-react":"^6.0.1","vite-bundle-analyzer":"^1.3.6"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/themeforge_0.1.1_1774760065887_0.26070185302582627","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@arpit194/themeforge","version":"0.2.0","description":"A lightweight, type-safe design token library for React","type":"module","sideEffects":false,"module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"dev":"vite build --watch","build":"npm run typecheck && vite build","analyze":"ANALYZE=true vite build","typecheck":"tsc --noEmit","lint":"eslint .","preview":"vite preview","release:patch":"git add -A && git diff --cached --quiet || git commit -m 'chore: pre-release sync' && npm version patch && git push && git push --tags","release:minor":"git add -A && git diff --cached --quiet || git commit -m 'chore: pre-release sync' && npm version minor && git push && git push --tags","release:major":"git add -A && git diff --cached --quiet || git commit -m 'chore: pre-release sync' && npm version major && git push && git push --tags"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"optionalDependencies":{"@rolldown/binding-linux-x64-gnu":"1.0.0-rc.12"},"devDependencies":{"@eslint/js":"^9.39.4","@types/node":"^24.12.0","@types/react":"^19.2.14","@types/react-dom":"^19.2.3","@vitejs/plugin-react":"^6.0.1","eslint":"^9.39.4","globals":"^17.4.0","react":"^19.2.4","react-dom":"^19.2.4","typescript":"~5.9.3","typescript-eslint":"^8.57.0","vite":"^8.0.1","vite-bundle-analyzer":"^1.3.6","vite-plugin-dts":"^4.5.4"},"_id":"@arpit194/themeforge@0.2.0","gitHead":"722fada75e3fcc8a3d16c55fbccd3c5ee6a901c2","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Q3iQXy3MuLqZ52gjUGqf5qqlZfVjmBQDPV6cTyZdSCMHRPBYj3pQKM4O7LectkkQQTvrS/S0J4GVgLOFqCC+MA==","shasum":"e538b0fa67d234d512d4fc57b0c17dfddc8d33c0","tarball":"https://registry.npmjs.org/@arpit194/themeforge/-/themeforge-0.2.0.tgz","fileCount":17,"unpackedSize":87412,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDKeM6uBR+wQd/80QSknLwk2iBzsbO4CjrgGgqsP5I2JQIgRXpM1t7WXGPmO95a2/v7KzhRohWpBaLHP2ZT8RVbvyo="}]},"_npmUser":{"name":"arpit194","email":"arpit.patel194@gmail.com"},"directories":{},"maintainers":[{"name":"arpit194","email":"arpit.patel194@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/themeforge_0.2.0_1774896118714_0.04675081216348409"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T04:54:25.830Z","modified":"2026-03-30T18:41:58.962Z","0.1.1":"2026-03-29T04:54:26.068Z","0.2.0":"2026-03-30T18:41:58.868Z"},"description":"A lightweight, type-safe design token library for React","maintainers":[{"name":"arpit194","email":"arpit.patel194@gmail.com"}],"readme":"# ThemeForge\n\nA lightweight, type-safe design token library for React. Define your brand colors and get a complete token system — primitive color scales, spacing, radius, shadows, typography, and semantic color tokens — all emitted as scoped CSS custom properties.\n\n## Features\n\n- Generates 11-shade color scales (50–950) from a single base hex\n- Scoped CSS variables — supports multiple `ThemeProvider` instances on the same page\n- Primitive tokens: colors, spacing, radius, shadows, typography (primitives + text styles)\n- Semantic color tokens: named roles (`bg-primary`, `text-on-dark`, `border-error`) resolved against the active theme at render time\n- Extend any token type with full TypeScript support via module augmentation\n- Zero runtime dependencies\n- React 18 and 19\n\n## Installation\n\n```bash\nnpm install @arpit194/themeforge\n```\n\n## Basic usage\n\n```tsx\nimport { ThemeProvider } from '@arpit194/themeforge'\n\n<ThemeProvider\n  theme={{ primary: '#7C3AED', secondary: '#F59E0B' }}\n>\n  <App />\n</ThemeProvider>\n```\n\nAll props are optional — unspecified tokens fall back to defaults.\n\n## CSS variables\n\nEvery token is injected as a scoped CSS custom property:\n\n```css\n/* Primitive colors */\n--tf-color-primary-500\n--tf-color-neutral-100\n\n/* Semantic colors */\n--tf-color-bg-primary\n--tf-color-text-on-dark\n--tf-color-border-error\n\n/* Other tokens */\n--tf-spacing-md\n--tf-radius-lg\n--tf-shadow-md\n--tf-font-size-xl\n--tf-text-h1-size\n```\n\n## useTheme\n\nAccess resolved token values anywhere in the tree:\n\n```tsx\nimport { useTheme } from '@arpit194/themeforge'\n\nfunction Card() {\n  const { colors, spacing, radius, shadows, typography, semantic } = useTheme()\n\n  return (\n    <div style={{\n      backgroundColor: colors.primary.shades[500],\n      padding: spacing.md,\n      borderRadius: radius.lg,\n      boxShadow: shadows.md,\n    }}>\n      ...\n    </div>\n  )\n}\n```\n\n## Tokens\n\n### Colors\n\nSeven built-in primitive scales, each with 11 shades (50–950):\n\n| Key | Default |\n|---|---|\n| `primary` | `#7C3AED` violet |\n| `secondary` | `#F59E0B` amber |\n| `neutral` | `#6B7280` gray |\n| `success` | `#22C55E` green |\n| `warning` | `#EAB308` yellow |\n| `error` | `#EF4444` red |\n| `info` | `#3B82F6` blue |\n\n### Semantic colors\n\nSemantic tokens map named roles to primitive shades — automatically updated when the theme changes. Use these in component styles instead of primitive vars.\n\n#### Background\n- `bg-page` · `bg-subtle` · `bg-surface` · `bg-surface-raised` — layout surfaces\n- `bg-primary` · `bg-primary-hover` · `bg-primary-active` · `bg-primary-disabled` · `bg-primary-selected` · `bg-primary-subtle`\n- Same pattern for `bg-secondary`\n- `bg-success` · `bg-success-subtle` · `bg-warning` · `bg-warning-subtle` · `bg-error` · `bg-error-hover` · `bg-error-active` · `bg-error-subtle` · `bg-info` · `bg-info-subtle`\n\n#### Text\n- `text-primary` · `text-secondary` · `text-disabled` · `text-inverse` · `text-placeholder`\n- `text-link` · `text-link-hover`\n- `text-on-dark` — use on saturated/dark backgrounds (e.g. `bg-primary`, `bg-error`)\n- `text-on-light` — use on light tinted backgrounds (e.g. `bg-primary-subtle`, `bg-error-subtle`)\n- `text-success` · `text-warning` · `text-error` · `text-info`\n\n#### Icon\n- `icon-primary` · `icon-secondary` · `icon-disabled` · `icon-inverse`\n- `icon-on-dark` · `icon-on-light`\n- `icon-success` · `icon-warning` · `icon-error` · `icon-info`\n\n#### Border\n- `border-default` · `border-subtle` · `border-strong`\n- `border-primary` · `border-primary-focus` · `border-primary-disabled`\n- Same pattern for `border-secondary`\n- `border-success` · `border-warning` · `border-error` · `border-info`\n\nOverride any semantic token by passing a `{ scale, shade }` ref:\n\n```tsx\n<ThemeProvider\n  semantic={{\n    'bg-primary': { scale: 'primary', shade: 600 },\n  }}\n>\n```\n\n### Spacing\n\nScale from `3xs` (0.125rem / 2px) to `10xl` (16rem / 256px). CSS: `--tf-spacing-md`\n\n### Radius\n\n`none` · `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `3xl` · `full`. CSS: `--tf-radius-lg`\n\n### Shadows\n\n`none` · `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `inner`. Defined as `ShadowLayer[]` arrays — each layer references spacing tokens for spatial values and the neutral scale for color:\n\n```tsx\n<ThemeProvider\n  shadows={{\n    md: [{ y: '2xs', blur: 'sm', colorShade: 800, opacity: 0.2 }],\n  }}\n>\n```\n\n### Typography\n\nPrimitive tokens (`fontFamilies`, `fontSizes`, `fontWeights`, `lineHeights`, `letterSpacing`) plus semantic text styles (`h1`–`h6`, `body-lg`, `body`, `body-sm`, `label`, `caption`, `code`).\n\nText style overrides are per-property — only specify what you want to change:\n\n```tsx\n<ThemeProvider typography={{\n  fontFamilies: { primary: 'Inter, sans-serif' },\n  textStyles: { h1: { weight: 'bold', letterSpacing: 'tight' } },\n}}>\n```\n\n## Module augmentation\n\nAdd custom keys to any token category with full TypeScript support:\n\n```ts\nimport type { ShadowDefinition, TextStyle, SemanticColorRef } from '@arpit194/themeforge'\n\ndeclare module '@arpit194/themeforge' {\n  interface CustomColorKeys    { brand: string }\n  interface CustomShadowKeys   { glow: ShadowDefinition }\n  interface CustomSpacingKeys  { section: string }\n  interface CustomTextStyleKeys { hero: TextStyle }\n  interface CustomSemanticKeys  { 'bg-brand': SemanticColorRef }\n}\n\n<ThemeProvider\n  theme={{ brand: '#FF6B35' }}\n  shadows={{ glow: [{ y: '3xs', blur: 'md', colorShade: 400, opacity: 0.4 }] }}\n  spacing={{ section: '7rem' }}\n  typography={{ textStyles: { hero: { size: '7xl', weight: 'bold' } } }}\n  semantic={{ 'bg-brand': { scale: 'brand', shade: 500 } }}\n>\n```\n\n## Scoped themes\n\nNest `ThemeProvider` for component-level theming:\n\n```tsx\n<ThemeProvider theme={{ primary: '#7C3AED' }}>\n  <App />\n  <ThemeProvider theme={{ primary: '#E11D48' }}>\n    <Sidebar />\n  </ThemeProvider>\n</ThemeProvider>\n```\n\nEach instance generates its own scoped CSS variables without leaking into siblings.\n\n## Custom shade generator\n\nReplace the built-in shade generator with your own:\n\n```tsx\nimport { ThemeProvider } from '@arpit194/themeforge'\nimport { generateShades } from 'your-oklch-library'\n\n<ThemeProvider generateShades={generateShades}>\n```\n\n`generateShades` is also exported for standalone use:\n\n```ts\nimport { generateShades } from '@arpit194/themeforge'\n\nconst { shades, anchor } = generateShades('#E11D48')\n// shades: { 50: '#fff0f3', ..., 950: '#3b000d' }\n// anchor: 600  ← shade where the original hex was placed\n```\n\n## MCP server\n\nA Claude MCP server is available so Claude can work with ThemeForge without needing to look things up:\n\n```bash\nnpm install -g @arpit194/themeforge-mcp\n```\n\nAdd `.mcp.json` at your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"themeforge\": {\n      \"type\": \"stdio\",\n      \"command\": \"themeforge-mcp\"\n    }\n  }\n}\n```\n\n### Available tools\n\n| Tool | Description |\n|---|---|\n| `list_tokens` | List all token keys and defaults for a category |\n| `list_semantic_by_group` | Filter semantic tokens by group (`bg`, `text`, `icon`, `border`) |\n| `get_css_var` | Get the CSS variable name for any token |\n| `suggest_tokens` | Get the right semantic tokens for a component and state |\n| `get_usage_example` | Get a code example for a common pattern |\n| `scan_augmentations` | Scan a project for `declare module` blocks to discover custom tokens |\n\n## Publishing\n\n```bash\n# Library\nnpm run release:patch   # or release:minor / release:major\n\n# MCP server (from mcp/)\ncd mcp && npm run release:patch\n```\n\nEach command bumps the version, commits, tags, and pushes. GitHub Actions publishes to npm on tag push. The two packages are versioned independently.\n","readmeFilename":"README.md"}