@brighterly/lib-lumee-ui

Brighterly design system — design tokens (and, over time, Vue 3 components).

Usage

// main.ts — load exactly ONE mode file per app (apps never mix modes)
import '@brighterly/lib-lumee-ui/client.css'    // one mode per product: client.css | admin.css | smartest-minds.css
import '@brighterly/lib-lumee-ui/style.css'     // component styles
import '@brighterly/lib-lumee-ui/fonts.css'     // self-hosted DS fonts at the token weights
import '@brighterly/lib-lumee-ui/scrollbar.css' // tints the thumb of every native scrollbar, the page's included — opt-in

<script setup lang="ts">
import { ItemAnswerHorizontal } from '@brighterly/lib-lumee-ui'
</script>

Style custom UI with the semantic --btly-* CSS variables and .btly-text-<style> typography classes. For rare JS needs (charts, inline styles): import { token, brand, textClass } from '@brighterly/lib-lumee-ui' — mode-agnostic var(--btly-…) reference strings.

Fonts ship with the package: fonts.css self-hosts Inter / Mona Sans / Roboto through @fontsource/* (runtime dependencies) at exactly the weights the typography tokens use.

Scrollbars: scrollbar.css styles only the thumb of every native scrollbar — the page's included — with the standard properties: scrollbar-color tints it brand-gray-200 on a transparent track, and scrollbar-width: thin is the closest native thickness to the Figma 4px pill. The bar itself stays the engine's: overlay where the platform overlays (macOS, iOS, Android), so it takes no layout space, classic where it does not (Windows). Never style ::-webkit-scrollbar* in an app or a component — any such rule turns that bar into a classic 12–15px lane that eats the content width. To hide one on purpose use scrollbar-width: none plus ::-webkit-scrollbar { display: none } (the pseudo covers Safari before 18.2); never set scrollbar-width / scrollbar-color otherwise — the sheet owns them.

Bundle size (opt-in): the lumee() Vite plugin makes an app's production build ship only the icons and Logo drawings its code uses (the full icon registry is ~58 KB gzip, the Logo art ~48 KB).

// nuxt.config.ts
import { lumee } from '@brighterly/lib-lumee-ui/vite'
export default defineNuxtConfig({ vite: { plugins: [lumee()] } })
// vite.config.ts: plugins: [vue(), lumee()]

It runs in production builds only (dev keeps everything), scans the project directory (the nearest package.json or .git above Vite's root) and prints [lumee] icons: N of 171 names kept · logo: N of 22 variants kept. Write icon names and Logo props as literals. A build warning … imports @brighterly/lib-lumee-ui but was not scanned means code outside the project (a workspace package, an npm Nuxt layer) uses the DS and its icons may be missing — move that code into the project or drop the plugin.

Requirements

For the full Figma ↔ code workflow, Claude needs the Figma plugin (figma@claude-plugins-official) — it provides the figma:* skills and the Figma MCP. This repo enables it via .claude/settings.json, but plugins are per-developer config and do not arrive with git clone, so each developer sets it up once:

1. Install — in Claude Code run /plugin and install figma (from claude-plugins-official).
2. Authenticate — /mcp → figma → Authenticate (opens a browser). Installed ≠ authenticated.
3. Verify — /mcp shows figma … ✓ Connected; /skills lists figma:*.

This brings every developer to the same Figma-enabled state. The repo ships only its own skill, brighterly-design-system (.claude/skills/); never vendor copies of the Figma plugin's skills.

Font Awesome agent tools

Icons in this DS are FontAwesome 7 Pro, so Claude also needs the official Font Awesome agent-tools plugin (icons@fontawesome-agent-tools) — it provides the icons:* skills (/suggest-icon, /add-icon, /fa-help, /setup-fa) for finding and verifying FA icons against the live FA library/docs instead of stale training data. Like the Figma plugin it is enabled via committed .claude/settings.json (its marketplace declared in extraKnownMarketplaces), but plugins are per-developer config and do not arrive with git clone, so each developer installs it once:

1. Add the marketplace — in Claude Code run /plugin marketplace add FortAwesome/fontawesome-agent-tools (or npx skills add FortAwesome/fontawesome-agent-tools for the skills without the plugin wrapper).
2. Install — /plugin install icons@fontawesome-agent-tools.
3. Verify — /skills lists icons:* (e.g. icons:suggest-icon).

Scope note: use these tools to find / verify the right FA icon name and to answer FA questions — how an icon lands in code is governed by the DS's own <Icon> component and registry, not the raw output of /add-icon (which emits FontAwesome's generic per-icon integration). Treat /add-icon output as reference, not the DS pattern. FA-Pro registry creds (NPM_FORTAWESOME_ACCESS, see below) are still required to install the icon packages themselves.

Publishing New Versions

Publishing is automatic and CI-only. .github/workflows/publish.yml has two jobs: verify (frozen install, component-structure check, the full pnpm build, lint, unit tests) runs on every PR and every push to main / staging / develop / sandbox; publish runs nothing of its own — on a push to main whose package.json version npm does not have yet, it takes the dist/ that verify built and runs npm publish. So a release is a version bump that reaches main:

1. Bump the version Use one of the following commands to update package.json and create a git tag:

   pnpm version patch   # 1.0.0 -> 1.0.1 (bug fixes)
   pnpm version minor   # 1.0.0 -> 1.1.0 (new features)
   pnpm version major   # 1.0.0 -> 2.0.0 (breaking changes)
   

2. Push to main (directly or through a PR):

   git push
   

3. The npm release is created automatically.

A push that does not change the version skips the publish job. Do not npm publish from a laptop: dist/ is gitignored, and only verify builds the one that ships.

Git Hooks

Pre-commit hook

Runs pnpm lint and pnpm typecheck on staged .ts / .vue files.

Prepare:

chmod +x _tools/git/pre-commit
ln -s ../../_tools/git/pre-commit .git/hooks/pre-commit

Pre-push hook

Validates that a release tag (v*) matches the version in package.json before pushing.

Prepare:

chmod +x _tools/git/pre-push
ln -s ../../_tools/git/pre-push .git/hooks/pre-push

Dependencies

Create .env:

cp .env.example .env

Edit .env and add NPM_FORTAWESOME_ACCESS (registry) and FIGMA_ACCESS_TOKEN (Code Connect publish — scopes below)

Install deps:

make install

FIGMA_ACCESS_TOKEN scopes

The token is consumed by one thing only: the Code Connect CLI (make figma:publish / figma:unpublish). The Figma MCP the agent reads designs with is a remote server on its own OAuth — no env token — so these scopes never affect get_design_context and friends.

Generate at Figma → Settings → Security → Personal access tokens with:

The last five are not used by any script yet — they are granted so a future tool needs no new token. Deliberately not granted: file_comments:write (would post as the maintainer), file_dev_resources:*, library_assets:read, folders:read, webhooks:*, current_user:read.

Tokens expire (90 days is Figma's default) — when publish starts returning 403, regenerate with the same set. Note the Variables REST API is Enterprise-gated and has no scope here at all, which is why tokens come from the designer's DTCG export (tokens/*.json) rather than a live pull.