kodeui 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +30 -2
  3. package/bin/kodeui.mjs +89 -0
  4. package/package.json +37 -4
  5. package/skill/kodeui/SKILL.md +105 -0
  6. package/skill/kodeui/assets/tokens.css +40 -0
  7. package/skill/kodeui/components/aurora-input/AuroraInput.tsx +153 -0
  8. package/skill/kodeui/components/aurora-input/aurora-input.css +218 -0
  9. package/skill/kodeui/components/aurora-input/index.ts +2 -0
  10. package/skill/kodeui/components/bloom-wall/BloomWall.tsx +90 -0
  11. package/skill/kodeui/components/bloom-wall/bloom-wall.css +10 -0
  12. package/skill/kodeui/components/bloom-wall/engine.ts +1022 -0
  13. package/skill/kodeui/components/bloom-wall/icons/icons-a.ts +818 -0
  14. package/skill/kodeui/components/bloom-wall/icons/icons-b.ts +827 -0
  15. package/skill/kodeui/components/bloom-wall/icons/index.ts +25 -0
  16. package/skill/kodeui/components/bloom-wall/icons/types.ts +8 -0
  17. package/skill/kodeui/components/bloom-wall/index.ts +12 -0
  18. package/skill/kodeui/components/bloom-wall/paint.ts +113 -0
  19. package/skill/kodeui/components/bloom-wall/palettes.ts +32 -0
  20. package/skill/kodeui/components/blur-in-text/BlurInText.tsx +53 -0
  21. package/skill/kodeui/components/blur-in-text/blur-in-text.css +14 -0
  22. package/skill/kodeui/components/blur-in-text/index.ts +2 -0
  23. package/skill/kodeui/components/glass-reveal/GlassReveal.tsx +108 -0
  24. package/skill/kodeui/components/glass-reveal/glass-reveal.css +126 -0
  25. package/skill/kodeui/components/glass-reveal/index.ts +2 -0
  26. package/skill/kodeui/components/glow-card/GlowCard.tsx +67 -0
  27. package/skill/kodeui/components/glow-card/glow-card.css +134 -0
  28. package/skill/kodeui/components/glow-card/index.ts +2 -0
  29. package/skill/kodeui/components/launch-chip/LaunchChip.tsx +180 -0
  30. package/skill/kodeui/components/launch-chip/icons.tsx +119 -0
  31. package/skill/kodeui/components/launch-chip/index.ts +3 -0
  32. package/skill/kodeui/components/launch-chip/launch-chip.css +345 -0
  33. package/skill/kodeui/components/ring-reveal/RingReveal.tsx +84 -0
  34. package/skill/kodeui/components/ring-reveal/index.ts +4 -0
  35. package/skill/kodeui/components/ring-reveal/ring-reveal.css +10 -0
  36. package/skill/kodeui/components/ring-reveal/ring.ts +298 -0
  37. package/skill/kodeui/components/rolling-text/RollingText.tsx +121 -0
  38. package/skill/kodeui/components/rolling-text/index.ts +4 -0
  39. package/skill/kodeui/components/rolling-text/roll.ts +94 -0
  40. package/skill/kodeui/components/rolling-text/rolling-text.css +43 -0
  41. package/skill/kodeui/components/use-live-transcript/index.ts +2 -0
  42. package/skill/kodeui/components/use-live-transcript/useLiveTranscript.ts +215 -0
  43. package/skill/kodeui/components/voice-input/VoiceInput.tsx +273 -0
  44. package/skill/kodeui/components/voice-input/icons.tsx +27 -0
  45. package/skill/kodeui/components/voice-input/index.ts +4 -0
  46. package/skill/kodeui/components/voice-input/useVoiceRecorder.ts +289 -0
  47. package/skill/kodeui/components/voice-input/voice-input.css +34 -0
  48. package/skill/kodeui/components/voice-note/VoiceNote.tsx +170 -0
  49. package/skill/kodeui/components/voice-note/index.ts +3 -0
  50. package/skill/kodeui/components/voice-note/noteFile.ts +25 -0
  51. package/skill/kodeui/components/voice-note/voice-note.css +45 -0
  52. package/skill/kodeui/references/aurora-input.md +44 -0
  53. package/skill/kodeui/references/bloom-wall.md +59 -0
  54. package/skill/kodeui/references/blur-in-text.md +17 -0
  55. package/skill/kodeui/references/frameworks.md +46 -0
  56. package/skill/kodeui/references/glass-reveal.md +40 -0
  57. package/skill/kodeui/references/glow-card.md +48 -0
  58. package/skill/kodeui/references/launch-chip.md +37 -0
  59. package/skill/kodeui/references/recipes.md +77 -0
  60. package/skill/kodeui/references/ring-reveal.md +35 -0
  61. package/skill/kodeui/references/rolling-text.md +19 -0
  62. package/skill/kodeui/references/theming.md +45 -0
  63. package/skill/kodeui/references/use-live-transcript.md +28 -0
  64. package/skill/kodeui/references/voice-input.md +60 -0
  65. package/skill/kodeui/references/voice-note.md +22 -0
  66. package/skill/kodeui/scripts/add.mjs +192 -0
  67. package/skill/kodeui/scripts/manifest.json +92 -0
@@ -0,0 +1,17 @@
1
+ # Blur-in Text
2
+
3
+ Words fade in one by one from a 10 px blur (0.5 s each, 0.08 s apart). Made for hero headlines.
4
+
5
+ **Folder:** `blur-in-text` · **Needs:** nothing · **Exports:** `BlurInText`
6
+
7
+ Props: `text` (required), `as` (element, default `span`; use `h1`/`h2`), `stagger` (0.08),
8
+ `duration` (0.5), `blur` (px, 10), `delay` (s, 0), plus any HTML attribute.
9
+
10
+ ```tsx
11
+ import { BlurInText } from '@/components/kodeui/blur-in-text';
12
+
13
+ <BlurInText as="h1" text="Build your ideas faster" />
14
+ <BlurInText as="p" text="Free while in beta." stagger={0.12} duration={0.8} blur={6} delay={0.4} />
15
+ ```
16
+
17
+ Pure CSS, so it is fine in server components. It plays on mount; change `key` to replay.
@@ -0,0 +1,46 @@
1
+ # Framework notes
2
+
3
+ ## Next.js, app router
4
+ - The add script puts `'use client'` at the top of every component file that uses hooks, so a
5
+ server component (a `page.tsx` without `'use client'`) can render them directly.
6
+ - State and refs that drive a component (hover state for Bloom Wall, the text of an input) must
7
+ live in a client component. Put the interactive section in its own file that starts with
8
+ `'use client'` (e.g. `components/hero.tsx`) and render that from the page.
9
+ - A finer split also works: keep the markup in the server page and only make the stateful
10
+ wrapper a client component. Client components such as `Glass` can be used straight from a
11
+ server page with string props (`<Glass step={4} kind="text" as="h1">…</Glass>`), but a server
12
+ file can't pass a component as a prop (`as={LaunchChip}`) or a function (`onMouseEnter`): do
13
+ those inside a `'use client'` file.
14
+ - Global CSS imports from component files are allowed in the app router, so the components'
15
+ `import './x.css'` lines just work.
16
+ - Import alias: most projects map `@/*` to `./*` or `./src/*` in `tsconfig.json`; check `paths`.
17
+
18
+ ## Next.js, pages router
19
+ - Next only allows global CSS imports in `pages/_app`. For each copied folder, delete the
20
+ `import './x.css';` line from its `.tsx` file and add `import '@/components/kodeui/<folder>/<x>.css';`
21
+ (or a relative path) to `pages/_app.tsx`. The add script prints a warning when it sees this.
22
+ - Components using browser APIs only run them in effects, so SSR is safe.
23
+
24
+ ## JavaScript-only projects
25
+ - Vite, Remix and React Router compile `.tsx` without TypeScript installed, so the files work as
26
+ they are.
27
+ - Next.js refuses `.tsx` files until TypeScript is installed: add `typescript`, `@types/react`
28
+ and `@types/node` as dev dependencies (Next writes a `tsconfig.json` on the next run and keeps
29
+ `allowJs`, so the user's `.js` files keep working). Ask before converting their project; if they
30
+ say no, convert the copied files to `.jsx` / `.js` by removing the type annotations only.
31
+
32
+ ## Vite, Remix / React Router 7, CRA
33
+ - CSS side-effect imports work as they are. Nothing else to do.
34
+
35
+ ## Astro
36
+ - Use the components inside a React island: `<Hero client:load />` from a `.tsx` component file.
37
+ `@astrojs/react` must be installed.
38
+
39
+ ## Tailwind, CSS modules, styled-components
40
+ - KodeUI ships plain CSS with `ku-` class names and `--ku-*` variables; Tailwind's preflight does
41
+ not override it. Use Tailwind for the user's own layout around the components; don't rewrite
42
+ the components in Tailwind.
43
+
44
+ ## Server rendering in general
45
+ - No component touches `window` or `document` while rendering. Canvas, audio and speech start in
46
+ effects, so they are safe with SSR and hydrate cleanly.
@@ -0,0 +1,40 @@
1
+ # Glass Reveal
2
+
3
+ While `active`, every `Glass` surface inside turns to frosted glass, in 4 stagger steps (step 1
4
+ first: 0.40 s in, 1.1 s back; step 4 last: 0.56 s in, 2.5 s back), text changes ink and gains a
5
+ dark halo so it stays readable over a busy background. After `active` turns false the wrapper
6
+ stays in a "fading" state for 2.65 s while everything settles back.
7
+
8
+ **Folder:** `glass-reveal` · **Needs:** nothing · **Exports:** `GlassReveal`, `Glass`
9
+
10
+ ## Props
11
+
12
+ `GlassReveal`: `active` (required), `as` (element, default `div`), `timeScale`, `onModeChange(mode)`
13
+ with mode `'active' | 'fading' | 'off'`, `className`, `style`, `children`.
14
+
15
+ `Glass`: `step` 1 to 4 (required), `kind` (`chip`, `button`, `pill`, `panel`, `link` are frosted;
16
+ `tile` only tints; `text`, `heading` change ink), `as` (element or a component, e.g. `LaunchChip`),
17
+ plus any prop or ref for that element.
18
+
19
+ ## Example
20
+
21
+ ```tsx
22
+ import { GlassReveal, Glass } from '@/components/kodeui/glass-reveal';
23
+
24
+ <GlassReveal active={hovering} style={{ position: 'relative', zIndex: 1 }}>
25
+ <Glass step={1} kind="chip" as="button" onMouseEnter={on} onMouseLeave={off}>New</Glass>
26
+ <Glass step={2} kind="pill" as="span">Plan a trip</Glass>
27
+ <Glass step={4} kind="panel" as="section">…</Glass>
28
+ </GlassReveal>
29
+ ```
30
+
31
+ ## Traps
32
+
33
+ - It only looks like glass when something bright moves behind it: pair it with Bloom Wall or Ring
34
+ Reveal (share one `active` state) or any glowing background.
35
+ - The element's own `background-color`, `border` and `color` are the look it starts and ends
36
+ with, so keep the surfaces' normal styles; Glass adds the frosted state on top.
37
+ - An Aurora Input inside a GlassReveal turns to glass on step 3 by itself.
38
+ - A frosted kind (`button`, `pill`…) replaces the element's own fill while active, so a
39
+ brand-coloured call-to-action turns to dark glass for a moment. If it must keep its colour,
40
+ leave it unwrapped or use `kind="tile"` (tint only), and tell the user which you chose.
@@ -0,0 +1,48 @@
1
+ # Glow Card
2
+
3
+ A card framed by a 1 px border of four colours that slowly spins (one turn in 40 s, 8 s on hover)
4
+ with a blurred copy of that border behind it as a glow; on hover the colours brighten over 0.6 s.
5
+ Keyboard focus lights it like hover. Ideal for an upgrade / pro card in a sidebar, a featured
6
+ pricing plan or a "what's new" card.
7
+
8
+ **Folder:** `glow-card` · **Needs:** nothing · **Exports:** `GlowCard`, `GlowCardTitle`, `GlowCardText`
9
+
10
+ ## Props
11
+
12
+ | Prop | Type | Default | What it does |
13
+ |---|---|---|---|
14
+ | `as` | `'button' \| 'a' \| 'div'` | `'button'` | The element inside the frame |
15
+ | `colors` | `[c1, c2, c3, c4]` | lagoon, fern, amber, coral | The four lights, in the order they run round |
16
+ | `spin` | seconds | 40 | One turn at rest |
17
+ | `hoverSpin` | seconds | 8 | One turn while hovered |
18
+ | `radius` | px | 16 | Outer corner radius |
19
+ | `hovered` | boolean | | Force the hover look |
20
+ | `className`, `style` | | | On the outer frame |
21
+ | anything else | | | `onClick`, `href`, `aria-*`… go on the inner element |
22
+
23
+ ## Example
24
+
25
+ ```tsx
26
+ import { GlowCard, GlowCardTitle, GlowCardText } from '@/components/kodeui/glow-card';
27
+
28
+ <GlowCard as="a" href="/pricing" colors={['#7c3aed', '#ec4899', '#f59e0b', '#06b6d4']}>
29
+ <GlowCardTitle>Go Pro</GlowCardTitle>
30
+ <GlowCardText>Unlimited projects and priority support.</GlowCardText>
31
+ </GlowCard>
32
+ ```
33
+
34
+ ## Traps
35
+
36
+ - The glow spreads a little outside the card: leave some room, and don't clip it with a parent's
37
+ `overflow: hidden` right at the card's edge.
38
+ - **Brand colours:** pass all four `colors`. With a two-colour brand use `[a, b, a, b]` (exact
39
+ brand colours) or `[a, lighter a, b, lighter b]` for more movement. Very dark brand colours (a
40
+ deep violet like `#7C3AED`) read dim on a dark card: mention it, and offer a lighter tint.
41
+ - **The rest of the card is still KodeUI green-grey.** `colors` only sets the border lights. To
42
+ match a brand fully, set these on the card's `className` (or a parent):
43
+ `--ku-glow-card-bg` (the card surface), `--ku-glow-card-bg-hover`, `--ku-glow-card-neutral` (the
44
+ dim part of the border), `--ku-text` / `--ku-text-2` (title and text) and `--ku-fern` (the
45
+ keyboard focus ring).
46
+ - **Host link and button styles leak in.** The inner element is an `<a>` or `<button>`, so a host
47
+ rule like `.sidebar a { padding: 8px; border-radius: 8px }` overrides the card's own padding
48
+ and corners. Scope that rule (`.sidebar > a`) or exclude `[class*="ku-"]`.
@@ -0,0 +1,37 @@
1
+ # Launch Chip
2
+
3
+ An announcement pill. After `delay` it blurs in; with `intro="splash"` a gradient pill wipes in
4
+ across it with a word and 8 tiny glowing icons that drift and fade, then collapses into a 26 px
5
+ round badge; the label slides in, and if there is a `secondaryLabel` it rolls up to it and back
6
+ (the pill's width follows) in one 8 s cycle. It is a `<button>`.
7
+
8
+ **Folder:** `launch-chip` · **Needs:** nothing · **Exports:** `LaunchChip`
9
+
10
+ ## Props
11
+
12
+ | Prop | Type | Default | What it does |
13
+ |---|---|---|---|
14
+ | `label` | string | required | Main line, e.g. "v2 is here" |
15
+ | `secondaryLabel` | string | | The line it rolls to |
16
+ | `word` | string | | Big word in the splash, e.g. "Bloom" |
17
+ | `badge` | string | | 1-2 characters in the round badge, e.g. "2" |
18
+ | `intro` | `'splash' \| 'grid' \| 'none'` | `'splash'` | `grid` = the timing to use with a Bloom Wall |
19
+ | `delay` | seconds | 1.3 | Before it enters |
20
+ | `icons` | ReactNode[] (8) | night-garden set | Replace the tiny splash icons |
21
+ | button props, `ref` | | | `onClick`, `onMouseEnter`, `aria-*`… |
22
+
23
+ ## Example
24
+
25
+ ```tsx
26
+ import { LaunchChip } from '@/components/kodeui/launch-chip';
27
+
28
+ <LaunchChip label="Acme 2.0 is here" secondaryLabel="Now with team spaces" word="New" badge="2" delay={0.4}
29
+ onClick={() => router.push('/changelog')} />
30
+ ```
31
+
32
+ ## Traps
33
+
34
+ - The intro plays once on mount; remount (change `key`) to replay it.
35
+ - To place it above a headline like the original, wrap the headline in `position: relative` and
36
+ give the chip `position: absolute; bottom: calc(100% + 24px); left: 50%; transform: translateX(-50%)`.
37
+ - Its ref is the natural `origin` for a Bloom Wall.
@@ -0,0 +1,77 @@
1
+ # Recipes
2
+
3
+ ## AI product hero (the full KodeUI look)
4
+ Launch Chip as the trigger, Blur-in headline, Voice Input, Glass Reveal over a Bloom Wall.
5
+ Add with: `node add.mjs bloom-wall glass-reveal launch-chip blur-in-text voice-input`.
6
+
7
+ ```tsx
8
+ 'use client';
9
+ import { useRef, useState } from 'react';
10
+ import { BloomWall } from '@/components/kodeui/bloom-wall';
11
+ import { GlassReveal, Glass } from '@/components/kodeui/glass-reveal';
12
+ import { LaunchChip } from '@/components/kodeui/launch-chip';
13
+ import { BlurInText } from '@/components/kodeui/blur-in-text';
14
+ import { VoiceInput } from '@/components/kodeui/voice-input';
15
+
16
+ export function Hero() {
17
+ const chip = useRef<HTMLElement>(null);
18
+ const [on, setOn] = useState(false);
19
+ return (
20
+ <section style={{ position: 'relative', overflow: 'hidden', isolation: 'isolate', minHeight: 720, background: '#0e1712' }}>
21
+ <BloomWall active={on} origin={chip} />
22
+ <GlassReveal active={on} style={{ position: 'relative', zIndex: 1, display: 'grid', justifyItems: 'center', gap: 24, padding: '200px 24px 64px' }}>
23
+ <div style={{ position: 'relative' }}>
24
+ <Glass step={1} kind="chip" as={LaunchChip} ref={chip}
25
+ label="Acme 2.0 is here" secondaryLabel="Now with voice" word="New" badge="2" intro="grid" delay={0.4}
26
+ style={{ position: 'absolute', bottom: 'calc(100% + 24px)', left: '50%', transform: 'translateX(-50%)' }}
27
+ onMouseEnter={() => setOn(true)} onMouseLeave={() => setOn(false)} onClick={() => setOn(false)} />
28
+ <Glass step={4} kind="text" as="h1"><BlurInText text="Build your ideas with Acme" /></Glass>
29
+ </div>
30
+ <div style={{ width: '100%', maxWidth: 874 }}>
31
+ <VoiceInput placeholder="Describe an idea, or click the mic and say it" />
32
+ </div>
33
+ <div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', justifyContent: 'center' }}>
34
+ <Glass step={2} kind="pill" as="button">Plan a trip</Glass>
35
+ <Glass step={2} kind="pill" as="button">Write a story</Glass>
36
+ </div>
37
+ </GlassReveal>
38
+ </section>
39
+ );
40
+ }
41
+ ```
42
+
43
+ ## Chat composer with voice
44
+ `node add.mjs voice-input`, then at the bottom of the chat (full width, up to about 874 px):
45
+
46
+ ```tsx
47
+ const voice = useRef<VoiceInputHandle>(null);
48
+ <VoiceInput
49
+ ref={voice}
50
+ value={draft}
51
+ onChange={setDraft}
52
+ onSubmit={sendText}
53
+ transcribe={false} // the note itself is the message
54
+ onVoiceNote={async (note) => {
55
+ addMessage(`🎤 voice note (${formatClock(note.seconds)})`);
56
+ voice.current?.removeNote(); // clear the box for the next one
57
+ const body = new FormData();
58
+ body.append('audio', note.blob, note.fileName);
59
+ await fetch('/api/voice', { method: 'POST', body });
60
+ }}
61
+ />
62
+ ```
63
+
64
+ `VoiceInputHandle` comes from the voice-input folder and `formatClock` from voice-note.
65
+
66
+ ## Sidebar upgrade card
67
+ `node add.mjs glow-card`, then at the bottom of the sidebar:
68
+ `<GlowCard as="a" href="/upgrade"><GlowCardTitle>Go Pro</GlowCardTitle><GlowCardText>…</GlowCardText></GlowCard>`.
69
+ It is designed for a narrow (about 200 px) dark sidebar.
70
+
71
+ ## "What's new" banner
72
+ `node add.mjs launch-chip` and place the chip above the page title; or `rolling-text` alone inside
73
+ an existing pill when the splash is too much.
74
+
75
+ ## Focus mode behind a card
76
+ `node add.mjs ring-reveal glass-reveal`: hovering a card opens a dark ring from it, and the rest
77
+ of the page goes to glass.
@@ -0,0 +1,35 @@
1
+ # Ring Reveal
2
+
3
+ The Bloom Wall's reveal on its own: a soft-edged ring grows out of an element (0.85 s, a faster
4
+ 0.588 s when re-entered mid-fold) and fills its parent with a dark colour, then folds back toward
5
+ the element when it ends. Good for a spotlight / focus mode behind a hovered button or card.
6
+
7
+ **Folder:** `ring-reveal` · **Needs:** nothing · **Exports:** `RingReveal`
8
+
9
+ ## Props
10
+
11
+ | Prop | Type | Default | What it does |
12
+ |---|---|---|---|
13
+ | `active` | boolean | required | Open or fold |
14
+ | `origin` | ref or `() => ({x, y})` | centre | Where the ring starts |
15
+ | `color` | CSS colour | `#060c09` | The backdrop colour |
16
+ | `fastFade` | boolean | `false` | Quicker fold |
17
+ | `timeScale` | number | 1 | Slow motion |
18
+ | `onIdle` | () => void | | Fold finished |
19
+ | `className`, `style` | | | On the canvas |
20
+
21
+ ## Example
22
+
23
+ ```tsx
24
+ const pill = useRef<HTMLButtonElement>(null);
25
+ const [open, setOpen] = useState(false);
26
+
27
+ <section style={{ position: 'relative', overflow: 'hidden' }}>
28
+ <RingReveal active={open} origin={pill} color="#060c09" />
29
+ <div style={{ position: 'relative', zIndex: 1 }}>
30
+ <button ref={pill} onMouseEnter={() => setOpen(true)} onMouseLeave={() => setOpen(false)}>Focus</button>
31
+ </div>
32
+ </section>
33
+ ```
34
+
35
+ Same positioning rule as Bloom Wall: it fills the nearest positioned parent, under the content.
@@ -0,0 +1,19 @@
1
+ # Rolling Text
2
+
3
+ Text in a small masked window that rolls up to the next line and back; the element's width follows
4
+ the line that is showing. Two items take one 8 s cycle; more items step through in turn.
5
+
6
+ **Folder:** `rolling-text` · **Needs:** nothing · **Exports:** `RollingText`
7
+
8
+ Props: `items` (string[], required; the first shows at rest), `delay` (s, default 0), `duration`
9
+ (s per two-item cycle, default 8), `loop` (default false: plays once), `className`, `style`.
10
+
11
+ ```tsx
12
+ import { RollingText } from '@/components/kodeui/rolling-text';
13
+
14
+ <span className="pill">
15
+ <RollingText items={['Now in beta', 'Free for students']} loop />
16
+ </span>
17
+ ```
18
+
19
+ It inherits font and colour. Screen readers get all items once, not the animation.
@@ -0,0 +1,45 @@
1
+ # Theming
2
+
3
+ The components read CSS variables with built-in fallbacks, so they look right with nothing set.
4
+ Change the look in two ways.
5
+
6
+ ## 1. Props (per instance)
7
+
8
+ | Component | Prop | Example |
9
+ |---|---|---|
10
+ | Glow Card | `colors` (4) | `colors={['#7c3aed', '#ec4899', '#f59e0b', '#06b6d4']}` |
11
+ | Aurora Input / Voice Input | `colors` | `colors={['#22d3ee', '#a78bfa', '#f472b6', '#34d399']}` |
12
+ | Voice Input | `glowColors` | centre first, then pairs outward (up to 7) |
13
+ | Bloom Wall | `palettes` | `[{ id: 'violet', name: 'Violet', primary: '#a78bfa', secondary: '#f472b6', accent: '#22d3ee', glow: '#a78bfa' }, …]` |
14
+ | Ring Reveal | `color` | the backdrop colour |
15
+
16
+ To match a brand, use the brand's own colours. The lights are drawn on dark surfaces at part
17
+ strength, so very dark colours look dim: say so, and offer lighter tints. Lists of four with
18
+ only two brand colours can repeat them (`[a, b, a, b]`) or alternate each with a lighter tint.
19
+ The border lights move best with at least two clearly different hues.
20
+
21
+ ## 2. CSS variables (for the whole app)
22
+
23
+ `node add.mjs … --tokens` copies `tokens.css` next to the components. Import it once (root layout
24
+ or main entry) and edit the values, or set the same variables in the user's own CSS:
25
+
26
+ | Variable | Default | Used for |
27
+ |---|---|---|
28
+ | `--ku-night`, `--ku-bg`, `--ku-panel` | `#060c09`, `#0a120e`, `#0e1712` | Backdrops |
29
+ | `--ku-surface`, `--ku-surface-high`, `--ku-surface-highest` | `#131e18`, `#192620`, `#213029` | Inputs, pills, buttons |
30
+ | `--ku-outline`, `--ku-outline-strong` | `#24342c`, `#33463c` | Borders |
31
+ | `--ku-text`, `--ku-text-2`, `--ku-text-3`, `--ku-link` | `#e8f1eb`, `#a2b6aa`, `#6e8579`, `#7fe3b0` | Text |
32
+ | `--ku-fern`, `--ku-firefly`, `--ku-amber`, `--ku-seaglass` | `#5ee08a`, `#e6f36a`, `#ffc14d`, `#3cd6c4` | Lights |
33
+ | `--ku-lagoon`, `--ku-coral`, `--ku-bloom`, `--ku-aurora` | `#4da8ff`, `#ff6b6b`, `#ff8fc8`, `#9d8bf7` | Lights |
34
+
35
+ Component surfaces have their own variables too (set them on the component's `className` or a
36
+ parent): Glow Card `--ku-glow-card-bg`, `--ku-glow-card-bg-hover`, `--ku-glow-card-neutral`;
37
+ Aurora Input and Voice Input `--ku-aurora-input-bg`, `--ku-aurora-input-neutral`. Text uses
38
+ `--ku-text*` and focus rings use `--ku-fern`.
39
+
40
+ Scope them to a section (`.my-hero { --ku-panel: #0b0b14; }`) to theme one area only.
41
+
42
+ ## Fonts
43
+
44
+ Components inherit the page font. The KodeUI site uses Inter for text and Fraunces for
45
+ headlines; nothing requires them.
@@ -0,0 +1,28 @@
1
+ # useLiveTranscript
2
+
3
+ A hook around the browser's speech recognition: words arrive while the user talks.
4
+
5
+ **Folder:** `use-live-transcript` · **Needs:** nothing · **Exports:** `useLiveTranscript`
6
+
7
+ `useLiveTranscript({ lang?, continuous = true, interim = true })` returns
8
+ `{ supported, listening, text, interim, error, start(), stop(), abort(), reset() }`.
9
+ `text` is every final word since the last `reset()`; `interim` is words still being worked out
10
+ (show them greyed after `text`). `supported` is false in Firefox and during server rendering.
11
+
12
+ ```tsx
13
+ import { useLiveTranscript } from '@/components/kodeui/use-live-transcript';
14
+
15
+ function Dictation() {
16
+ const { supported, listening, text, interim, error, start, stop } = useLiveTranscript({ lang: 'en-US' });
17
+ if (!supported) return <p>This browser can't turn speech into text.</p>;
18
+ return (
19
+ <>
20
+ <button onClick={listening ? stop : start}>{listening ? 'Stop' : 'Dictate'}</button>
21
+ <p>{text} <span style={{ opacity: 0.5 }}>{interim}</span></p>
22
+ {error && <p role="alert">{error}</p>}
23
+ </>
24
+ );
25
+ }
26
+ ```
27
+
28
+ Privacy: Chrome sends the audio to Google and Edge to Microsoft. Say so to the user.
@@ -0,0 +1,60 @@
1
+ # Voice Input
2
+
3
+ The Aurora Input with a microphone. Click the mic: a colourful glow (the `voice-glow` library)
4
+ rises from the bottom of the box and moves with the voice, the mic becomes a stop button and an ✕
5
+ appears. Click stop: the glow gathers into one beam and sweeps side to side ("Thinking…", at least
6
+ 1.6 s), then a voice note appears in the box with play, length, Save and remove. Playing the note
7
+ makes the glow react to it. ✕ or Escape cancels. With `transcribe` on, the words appear in the
8
+ box while you speak.
9
+
10
+ **Folder:** `voice-input` · **Needs:** `aurora-input`, `voice-note`, `use-live-transcript`, npm `voice-glow` ·
11
+ **Exports:** `VoiceInput`, `useVoiceRecorder`
12
+
13
+ ## Props
14
+
15
+ Everything Aurora Input takes (except `overlay` and `top`), plus:
16
+
17
+ | Prop | Type | Default | What it does |
18
+ |---|---|---|---|
19
+ | `onVoiceNote(note)` | | | A recording is ready: `{ blob, url, seconds, mimeType, fileName }` |
20
+ | `transcribe` | boolean | `true` | Live words while speaking (browser speech service) |
21
+ | `lang` | string | browser | e.g. `'en-GB'` for the transcript |
22
+ | `glowColors` | string[] | nature lights | Glow lobe colours, centre first |
23
+ | `trailingActions` | ReactNode | | Buttons after the mic and ✕ |
24
+ | `timeScale` | number | 1 | Slow motion |
25
+
26
+ A ref gives `{ start(), finish(), cancel(), removeNote(), state }`. `removeNote()` clears the
27
+ note from the box (and revokes its `url`, so upload the `blob`, not the url).
28
+
29
+ ## Example
30
+
31
+ ```tsx
32
+ import { VoiceInput } from '@/components/kodeui/voice-input';
33
+
34
+ const [text, setText] = useState('');
35
+ <VoiceInput
36
+ value={text}
37
+ onChange={setText}
38
+ onSubmit={(t) => send(t)}
39
+ onVoiceNote={({ blob, fileName, seconds }) => upload(blob, fileName, seconds)}
40
+ placeholder="Ask anything, or click the mic"
41
+ />
42
+ ```
43
+
44
+ ## Traps
45
+
46
+ - Install `voice-glow` (the add script prints the command).
47
+ - The mic works only on https or localhost, and only after a click. A blocked or missing mic
48
+ shows a short message in the box.
49
+ - Privacy: the live transcript sends audio to the browser's speech service (Chrome: Google,
50
+ Edge: Microsoft). Use `transcribe={false}` when the audio must stay on the device, and tell the
51
+ user either way. The recording itself never leaves the page unless their `onVoiceNote` uploads it.
52
+ - Firefox has no speech recognition: recording works, live words don't.
53
+ - **Send-as-soon-as-ready chats:** the note stays in the box after `onVoiceNote` until it is
54
+ removed, so call `ref.current?.removeNote()` after sending. And `transcribe` types the spoken
55
+ words into the box as a draft, which would duplicate the voice note as text: use
56
+ `transcribe={false}` there, or clear the draft when the note is sent.
57
+ - **Recording format** depends on the browser: WebM/Opus in Chrome, Edge and Firefox, MP4/AAC in
58
+ Safari. `note.mimeType` and `note.fileName` (with the right extension) say which; servers should
59
+ accept both.
60
+ - `useVoiceRecorder` is the state machine on its own, for building a different voice UI.
@@ -0,0 +1,22 @@
1
+ # Voice Note
2
+
3
+ A pill for a recording: a round play / pause button, bars that move while it plays, the length as
4
+ m:ss, a Save link (downloads the file) and an optional ✕. Pops in with a short blur.
5
+
6
+ **Folder:** `voice-note` · **Needs:** nothing · **Exports:** `VoiceNote`
7
+
8
+ Props: `src` (audio URL, required), `seconds` (required), `fileName` (Save's file name, default
9
+ "voice-note"), `onRemove` (shows the ✕), `onPlayingChange(playing, stream)` (stream = the audio as
10
+ a MediaStream for a glow), `onBeforePlay`, `playable` (default true), `label` ("Voice note"),
11
+ `saveLabel` ("Save"), `className`. A ref gives `{ play(), stop(), playing, audio }`.
12
+
13
+ ```tsx
14
+ import { VoiceNote } from '@/components/kodeui/voice-note';
15
+
16
+ <VoiceNote src={note.url} seconds={note.seconds} fileName="memo.webm" onRemove={() => setNote(null)} />
17
+ ```
18
+
19
+ The folder also exports `formatClock(seconds)` (`72` → `"1:12"`), handy for chat messages like
20
+ "🎤 voice note (1:12)".
21
+
22
+ `src` can be any audio URL, including `URL.createObjectURL(blob)`; revoke object URLs you make.