{"_id":"@molecule/app-theme","_rev":"4-37af18db5935a1109091d86cf9bca1c7","name":"@molecule/app-theme","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@molecule/app-theme","version":"1.0.0","keywords":["molecule","theme","styling","dark-mode"],"license":"Apache-2.0","_id":"@molecule/app-theme@1.0.0","maintainers":[{"name":"vialoh","email":"npm@vialoh.me"}],"homepage":"https://github.com/molecule-dev/molecule/tree/main/packages/app/core/theme","bugs":{"url":"https://github.com/molecule-dev/molecule/issues"},"dist":{"shasum":"504a7173658e96a594737ee2c6c382119514c3dc","tarball":"https://registry.npmjs.org/@molecule/app-theme/-/app-theme-1.0.0.tgz","fileCount":22,"integrity":"sha512-yAdNSokB/5hjR9U3haRxTOtLwjvG0YFxBh9mnhHeUl2lwS4TxIX1zbjOmeZkfwQcrX6lz6xILUmOjsVv1yHQgQ==","signatures":[{"sig":"MEQCIF/aOvIEecrNdfTjclE4MFcNTkHIOjB3vVV5lkroBXdVAiA47pea92CM0MVxPo93g1L4k+8uGqdNEeq9ei+biPHQ0Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":36841},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"92623e72a527ca467963169420f4cf07533e4699","scripts":{"test":"vitest run","build":"tsc","test:watch":"vitest"},"_npmUser":{"name":"vialoh","email":"npm@vialoh.me"},"repository":{"url":"git+https://github.com/molecule-dev/molecule.git","type":"git","directory":"packages/app/core/theme"},"_npmVersion":"11.12.1","description":"Theme interface and utilities for molecule.dev","directories":{},"_nodeVersion":"25.9.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"4.1.10","typescript":"6.0.3","@types/node":"26.1.2","@molecule/app-bond":"1.0.0"},"peerDependencies":{"@molecule/app-bond":"^1.0.0"},"_npmOperationalInternal":{"tmp":"tmp/app-theme_1.0.0_1785796145836_0.03293769042520589","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@molecule/app-theme","version":"1.0.1","keywords":["molecule","theme","styling","dark-mode"],"license":"Apache-2.0","_id":"@molecule/app-theme@1.0.1","maintainers":[{"name":"vialoh","email":"npm@vialoh.me"}],"homepage":"https://github.com/molecule-dev/molecule/tree/main/packages/app/core/theme","bugs":{"url":"https://github.com/molecule-dev/molecule/issues"},"dist":{"shasum":"cede20b3d56e32e4de112e894d8fe1d1d2118a09","tarball":"https://registry.npmjs.org/@molecule/app-theme/-/app-theme-1.0.1.tgz","fileCount":23,"integrity":"sha512-gKFFi940uMU5BRaS+ZfEiYg9vS9yY1zorqYm0d6hAGAqkz4SwktmIywAKJcJrqsCBhtugZSLrDlz7C6/CDgEWw==","signatures":[{"sig":"MEUCIQDCEbWpFnaQ1uVMWL40/r3dhxj0uQAlXMuMnthaSzwyDgIgf6MDjFvu5cHDfwa0rE91OimjHTQo2VeFgT6O+AsAeXo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@molecule%2fapp-theme@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":46534},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"b555adc9864b84ef80ca987e046ba6b0a3500195","scripts":{"test":"vitest run","build":"tsc","test:watch":"vitest"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0bd7a03c-d58a-4384-9067-e3ca4b0681d9"}},"repository":{"url":"git+https://github.com/molecule-dev/molecule.git","type":"git","directory":"packages/app/core/theme"},"_npmVersion":"12.0.2","description":"Theme interface and utilities for molecule.dev","directories":{},"_nodeVersion":"22.23.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"4.1.10","typescript":"6.0.3","@types/node":"26.1.2","@molecule/app-bond":"1.0.1"},"peerDependencies":{"@molecule/app-bond":"^1.0.1"},"_npmOperationalInternal":{"tmp":"tmp/app-theme_1.0.1_1785912496261_0.9404996138604964","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@molecule/app-theme","version":"1.0.2","keywords":["molecule","theme","styling","dark-mode"],"license":"Apache-2.0","_id":"@molecule/app-theme@1.0.2","maintainers":[{"name":"vialoh","email":"npm@vialoh.me"}],"homepage":"https://github.com/molecule-dev/molecule/tree/main/packages/app/core/theme","bugs":{"url":"https://github.com/molecule-dev/molecule/issues"},"dist":{"shasum":"d4d1360cb0dd50d4fd33ac8a1694a35beb24e844","tarball":"https://registry.npmjs.org/@molecule/app-theme/-/app-theme-1.0.2.tgz","fileCount":23,"integrity":"sha512-2q/LYICaa6Rr0ZfOkX1Vl/IPGnea2zuAQ/U7h/SBb9UfeUnIWM7bVWxlteqhqaJqpkI8RwxM9hhyLWoT7z+Fdw==","signatures":[{"sig":"MEUCIBts5+LNf7tzNfPeaD1SIYWYlb8HCdqfxCpQHhRmIaABAiEA/kX3bzM0FdkmLK+kI/ShgLvSCdzG3lc2iHd+XpXgGlM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@molecule%2fapp-theme@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":47477},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"de71ab873a1271cd66f65346c7e2828cf559ceb6","scripts":{"test":"vitest run","build":"tsc","test:watch":"vitest"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0bd7a03c-d58a-4384-9067-e3ca4b0681d9"}},"repository":{"url":"git+https://github.com/molecule-dev/molecule.git","type":"git","directory":"packages/app/core/theme"},"_npmVersion":"12.0.2","description":"Theme interface and utilities for molecule.dev","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"4.1.11","typescript":"6.0.3","@types/node":"26.1.2","@molecule/app-bond":"1.0.1"},"peerDependencies":{"@molecule/app-bond":"^1.0.1"},"_npmOperationalInternal":{"tmp":"tmp/app-theme_1.0.2_1789344167063_0.36368975574123286","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"_id":"@molecule/app-theme@1.0.3","bugs":{"url":"https://github.com/molecule-dev/molecule/issues"},"dist":{"shasum":"8248ab11c30026fe9961a04d2c2a4ff3cad228be","tarball":"https://registry.npmjs.org/@molecule/app-theme/-/app-theme-1.0.3.tgz","fileCount":23,"integrity":"sha512-lx+HeN+F24iO6H5jq+XBNViWwgPeWNQnbaZazpxmlMMMoEb8yqjOVB3PrtRizOb8VuupR338JZCx0gwnzq5A2w==","signatures":[{"sig":"MEQCIBs4PEeG978zBLfEzBXzJF6Q0A6rhMETDgiaLHgyWHyXAiBfC3a68HOzTem6vPgkiAqT8KZaQb/6Fp+oz02jFLMFBA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGO6OBRWIH0A4KzZCHna+vcECYSyv+QkgNm+wzYQbS5SAiEA45cWyGS+qjwnmX98j/f0XXhZwKn0M27pzB4wHe7/2go="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@molecule%2fapp-theme@1.0.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":47446},"main":"dist/index.js","name":"@molecule/app-theme","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"80c23a410fe0952f0800a99180ecf221de9923e6","license":"Apache-2.0","scripts":{"test":"vitest run","build":"tsc","test:watch":"vitest"},"version":"1.0.3","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0bd7a03c-d58a-4384-9067-e3ca4b0681d9"}},"homepage":"https://www.molecule.dev/packages/app-theme","keywords":["molecule","theme","styling","dark-mode"],"repository":{"url":"git+https://github.com/molecule-dev/molecule.git","type":"git","directory":"packages/app/core/theme"},"_npmVersion":"12.0.2","description":"Theme interface and utilities for molecule.dev","directories":{},"maintainers":[{"name":"vialoh","email":"npm@vialoh.me"}],"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"4.1.11","typescript":"6.0.3","@types/node":"26.1.2","@molecule/app-bond":"1.0.2"},"peerDependencies":{"@molecule/app-bond":"^1.0.1"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/app-theme_1.0.3_1789917719635_0.6159064473505806"}}},"time":{"created":"2026-08-03T22:29:05.670Z","modified":"2026-09-20T15:22:00.065Z","1.0.0":"2026-08-03T22:29:05.957Z","1.0.1":"2026-08-05T06:48:16.413Z","1.0.2":"2026-09-14T00:02:47.199Z","1.0.3":"2026-09-20T15:21:59.734Z"},"bugs":{"url":"https://github.com/molecule-dev/molecule/issues"},"license":"Apache-2.0","homepage":"https://www.molecule.dev/packages/app-theme","keywords":["molecule","theme","styling","dark-mode"],"repository":{"url":"git+https://github.com/molecule-dev/molecule.git","type":"git","directory":"packages/app/core/theme"},"description":"Theme interface and utilities for molecule.dev","maintainers":[{"name":"vialoh","email":"npm@vialoh.me"}],"readme":"<!--\nAUTO-GENERATED — DO NOT EDIT THIS FILE.\nGenerated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.\nEdits here are overwritten on the next commit (molecule's pre-commit hook regenerates).\nTo change this document, edit the module-level JSDoc in src/index.ts.\nGenerated: 2026-09-13T23:39:57.945Z\n-->\n\n# @molecule/app-theme\n\n> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.\n> It is written to be read by coding agents as much as by people, and is generated from this\n> package's source — edit `src/index.ts` JSDoc, not this file.\n\nTheme interface and utilities for molecule.dev.\n\nFramework-agnostic theme contract — a {@link Theme} (colors, spacing,\ntypography, radii, shadows, z-index) plus a {@link ThemeProvider} bond for\nreading/switching themes, dark/light toggling, and change subscriptions.\nBond a provider (e.g. `@molecule/app-theme-css-variables`, which applies the\npalette as CSS variables) at startup; {@link lightTheme}/{@link darkTheme}\nare the base defaults.\n\n## Quick Start\n\n```typescript\nimport { getProvider } from '@molecule/app-theme'\n\nconst theme = getProvider() // null until a bond is wired at startup\ntheme?.toggleMode() // light <-> dark\nconst unsubscribe = theme?.subscribe((t) => applyBranding(t))\n```\n\n## Type\n\n`core`\n\n## Installation\n\n```bash\nnpm install @molecule/app-theme @molecule/app-bond\n```\n\n## API\n\n### Interfaces\n\n#### `Theme`\n\nComplete theme definition.\n\n```typescript\ninterface Theme {\n  name: string\n  mode: 'light' | 'dark'\n  colors: ThemeColors\n  breakpoints: ThemeBreakpoints\n  spacing: ThemeSpacing\n  typography: ThemeTypography\n  borderRadius: ThemeBorderRadius\n  shadows: ThemeShadows\n  transitions: ThemeTransitions\n  zIndex: ThemeZIndex\n}\n```\n\n#### `ThemeBorderRadius`\n\nBorder radius scale.\n\n```typescript\ninterface ThemeBorderRadius {\n  none: string\n  sm: string\n  md: string\n  lg: string\n  xl: string\n  full: string\n}\n```\n\n#### `ThemeBreakpoints`\n\nResponsive viewport breakpoints from mobileS (320px) to desktop (2560px).\n\n```typescript\ninterface ThemeBreakpoints {\n  mobileS: string // 320px\n  mobileM: string // 375px\n  mobileL: string // 425px\n  tablet: string // 768px\n  laptop: string // 1024px\n  laptopL: string // 1440px\n  desktop: string // 2560px\n}\n```\n\n#### `ThemeColors`\n\nColor palette definition.\n\n```typescript\ninterface ThemeColors {\n  // Base colors\n  background: string\n  backgroundSecondary: string\n  backgroundTertiary: string\n  surface: string\n  surfaceSecondary: string\n  inputBackground: string\n\n  // Text colors\n  text: string\n  textSecondary: string\n  textTertiary: string\n  textInverse: string\n\n  // Brand colors\n  primary: string\n  primaryLight: string\n  primaryDark: string\n  secondary: string\n  secondaryLight: string\n  secondaryDark: string\n\n  // Semantic colors\n  success: string\n  successLight: string\n  warning: string\n  warningLight: string\n  error: string\n  errorLight: string\n  info: string\n  infoLight: string\n\n  // Border colors\n  border: string\n  borderSecondary: string\n  borderFocus: string\n\n  // Other\n  overlay: string\n  shadow: string\n}\n```\n\n#### `ThemeProvider`\n\nManages theme state including the active theme, mode toggling,\nand change subscriptions.\n\n```typescript\ninterface ThemeProvider {\n  /**\n   * Returns the currently active theme.\n   */\n  getTheme(): Theme\n\n  /**\n   * Sets the active theme by reference or by name.\n   *\n   * @param theme - A `Theme` object or a theme name string to activate.\n   */\n  setTheme(theme: Theme | string): void\n\n  /**\n   * Toggles between light and dark mode for the active theme.\n   */\n  toggleMode(): void\n\n  /**\n   * Subscribes to theme changes. The callback fires whenever\n   * `setTheme()` or `toggleMode()` is called.\n   *\n   * @param callback - Invoked with the new theme after each change.\n   * @returns An unsubscribe function.\n   */\n  subscribe(callback: (theme: Theme) => void): () => void\n\n  /**\n   * Returns all registered themes. Optional — not all providers\n   * support multiple themes.\n   */\n  getThemes?(): Theme[]\n\n  /**\n   * Returns the theme a render WITHOUT a browser produces — a server or\n   * build-time render, which has no storage and no `prefers-color-scheme`\n   * to read. A hydrating client renders this theme first, so its markup\n   * matches what the server sent, and switches to `getTheme()` right\n   * after. Optional — a provider whose theme cannot differ between the two\n   * need not implement it.\n   */\n  getServerTheme?(): Theme\n}\n```\n\n#### `ThemeShadows`\n\nBox-shadow scale from none to xl for elevation levels.\n\n```typescript\ninterface ThemeShadows {\n  none: string\n  sm: string\n  md: string\n  lg: string\n  xl: string\n}\n```\n\n#### `ThemeSpacing`\n\nTheme spacing scale mapping size tokens (xs–3xl) to CSS values (e.g. '4px', '16px').\n\n```typescript\ninterface ThemeSpacing {\n  xs: string // 4px\n  sm: string // 8px\n  md: string // 16px\n  lg: string // 24px\n  xl: string // 32px\n  xxl: string // 48px\n  xxxl: string // 64px\n}\n```\n\n#### `ThemeTransitions`\n\nCSS transition duration presets (fast, normal, slow).\n\n```typescript\ninterface ThemeTransitions {\n  fast: string\n  normal: string\n  slow: string\n}\n```\n\n#### `ThemeTypography`\n\nTypography scale (font families, sizes, weights, and line heights).\n\n```typescript\ninterface ThemeTypography {\n  fontFamily: {\n    sans: string\n    serif: string\n    mono: string\n  }\n  fontSize: {\n    xs: string // 12px\n    sm: string // 14px\n    base: string // 16px\n    lg: string // 18px\n    xl: string // 20px\n    '2xl': string // 24px\n    '3xl': string // 30px\n    '4xl': string // 36px\n    '5xl': string // 48px\n  }\n  fontWeight: {\n    light: number\n    normal: number\n    medium: number\n    semibold: number\n    bold: number\n  }\n  lineHeight: {\n    tight: number\n    normal: number\n    relaxed: number\n  }\n}\n```\n\n#### `ThemeZIndex`\n\nTheme z-index scale for layering UI elements (dropdowns, modals, toasts, etc.).\n\n```typescript\ninterface ThemeZIndex {\n  hide: number\n  base: number\n  dropdown: number\n  sticky: number\n  fixed: number\n  modal: number\n  popover: number\n  tooltip: number\n  toast: number\n}\n```\n\n### Functions\n\n#### `createDarkTheme(overrides)`\n\nCreates a dark theme by merging default dark-mode tokens with\noptional overrides for colors, spacing, typography, etc.\n\n```typescript\nfunction createDarkTheme(overrides?: Partial<Theme>): Theme\n```\n\n- `overrides` — Partial theme tokens to merge over the defaults.\n\n**Returns:** A complete `Theme` object with `mode: 'dark'`.\n\n#### `createLightTheme(overrides)`\n\nCreates a light theme by merging default light-mode tokens with\noptional overrides for colors, spacing, typography, etc.\n\n```typescript\nfunction createLightTheme(overrides?: Partial<Theme>): Theme\n```\n\n- `overrides` — Partial theme tokens to merge over the defaults.\n\n**Returns:** A complete `Theme` object with `mode: 'light'`.\n\n#### `getProvider()`\n\nRetrieves the bonded theme provider, or `null` if none is configured.\n\n```typescript\nfunction getProvider(): ThemeProvider | null\n```\n\n**Returns:** The bonded theme provider, or `null`.\n\n#### `hasProvider()`\n\nChecks whether a theme provider is currently bonded.\n\n```typescript\nfunction hasProvider(): boolean\n```\n\n**Returns:** `true` if a theme provider is bonded.\n\n#### `setProvider(provider)`\n\nRegisters a theme provider as the active singleton.\n\n```typescript\nfunction setProvider(provider: ThemeProvider): void\n```\n\n- `provider` — The theme provider implementation to bond.\n\n### Constants\n\n#### `darkColors`\n\nDefault dark theme colors.\n\n```typescript\nconst darkColors: ThemeColors\n```\n\n#### `darkTheme`\n\nDefault dark theme.\n\n```typescript\nconst darkTheme: Theme\n```\n\n#### `defaultBorderRadius`\n\nDefault border radius.\n\n```typescript\nconst defaultBorderRadius: ThemeBorderRadius\n```\n\n#### `defaultBreakpoints`\n\nDefault responsive breakpoints (320px mobileS → 2560px desktop).\n\n```typescript\nconst defaultBreakpoints: ThemeBreakpoints\n```\n\n#### `defaultShadows`\n\nDefault box-shadow scale (none → xl, rgba-based).\n\n```typescript\nconst defaultShadows: ThemeShadows\n```\n\n#### `defaultSpacing`\n\nDefault spacing scale (4px xs → 64px xxxl).\n\n```typescript\nconst defaultSpacing: ThemeSpacing\n```\n\n#### `defaultTransitions`\n\nDefault CSS transition durations (150ms fast, 250ms normal, 350ms slow).\n\n```typescript\nconst defaultTransitions: ThemeTransitions\n```\n\n#### `defaultTypography`\n\nDefault typography scale (system font stacks, rem-based sizes, weight/line-height presets).\n\n```typescript\nconst defaultTypography: ThemeTypography\n```\n\n#### `defaultZIndex`\n\nDefault z-index scale.\n\n```typescript\nconst defaultZIndex: ThemeZIndex\n```\n\n#### `lightColors`\n\nDefault light theme colors.\n\n```typescript\nconst lightColors: ThemeColors\n```\n\n#### `lightTheme`\n\nDefault light theme.\n\n```typescript\nconst lightTheme: Theme\n```\n\n## Available Providers\n\n| Provider      | Package                                          |\n| ------------- | ------------------------------------------------ |\n| CSS Variables | `@molecule/app-theme-css-variables`              |\n| Liquid Glass  | `@molecule/app-theme-css-variables-liquid-glass` |\n\n## Injection Notes\n\n### Requirements\n\nPeer dependencies:\n\n- `@molecule/app-bond` ^1.0.1\n\n### Runtime Dependencies\n\n- `@molecule/app-bond`\n\n- **Recoloring: find the REAL source of truth first.** Apps scaffolded from a\n  template ship a per-app stylesheet (e.g. `app/src/theme.css`) that\n  hardcodes the `--color-*` variables and loads AFTER the bond — its values\n  win, and editing this package's `Theme` objects (or the bond's palette) has\n  NO visible effect there. Precedence: per-app theme stylesheet > theme\n  bond > base defaults. Recolor by editing whichever file actually defines\n  the variables; the bond's `Theme` palette applies only when no per-app\n  stylesheet defines colors.\n- Read theme values through the provider or the CSS variables it emits —\n  never hardcode hex values in components; surfaces and status colors come\n  from the theme so light AND dark both work.\n- {@link getProvider} returns `null` when nothing is bonded — theme switching\n  is optional; guard rather than throw.\n","readmeFilename":"README.md"}