Skip to content
helixui

Week 0 — open-sourcing helixui

Wayne, May 25 2026

This is the first devlog. The format is informal: every other Sunday or so, I write down what landed, what got punted, what almost broke, and what I’m thinking about. No marketing voice. You catch us in public; if something looks like a mess, it probably is a mess and I’ll say so.

What landed

  • create-helixui-app with four templates. The agent-ui one ended up being my favorite — it’s the smallest reasonable chat shell you can have with proper a11y.
  • DNA URL sharing in the lab. This is the single feature I expect to drive the most “huh, cool” reactions when we go public. The hash encoding is base64 of the gene shorthand; ~80 bytes per theme.
  • MCP integration guides for Claude Code, Cursor, Copilot, Windsurf, and tool-agnostic AGENTS.md. Five separate docs because the actual wiring differs more than I thought.
  • DataTable v0.1. Took longer than the RFC suggested because I kept second-guessing whether to depend on Tanstack Table. Ended up not — the v0 is ~400 lines of plain React, no dependency. We’ll reconsider Tanstack for virtualization in v0.2.
  • CSS-variable IntelliSense. t('color.bg.action.brand.default') now autocompletes to a typed string. The build emits a HelixUICssVar union with 130+ literal members; TypeScript handles it fine.
  • 86 → 89 components. Added FileUpload, CurrencyInput, DateRangePicker — the three biggest gaps for “you can build a real SaaS app with this.”
  • The NO list. Pinned at the top of MANIFESTO.md. “What helixui won’t do” turned out to be harder to write than the principles section.

What I broke (and fixed)

  • Got the JSON Schema for spec.md so strict that 85 of 86 existing specs failed validation. Walked it back to additionalProperties: true and only enforced the keys we care about. Lesson: ship strict schemas with grandfathering, not without.
  • The DNA URL hash encoded the full DNA object with allele metadata. Result: 2 KB URLs. Switched to encoding the gene shorthand only and reconstructing the full DNA on load. 80 bytes.
  • A 'use client' sweep that I thought would be one-line added — but one component had a // @ts-expect-error on a directive-conflicting import. Untangled it; passed.

What I punted

  • A real benchmark suite. The AI-friendly blog had unaudited numbers in it (38% → 91%). I removed them and wrote an honest “coming, not done” section instead. Building the benchmark properly is two weeks of focused work and the launch can’t wait. We’ll ship numbers when they’re real.
  • Figma library. Token Studio import is documented but the actual component file doesn’t exist. Hiring a designer for a one-month contract is the next move; I don’t have the bandwidth.
  • Live playgrounds in docs pages. Astro + MDX + React Islands works, but wiring each of 89 components is a week. Components have their spec.md examples; that’s not the same and I know it.

What I’m thinking about

The biggest open question for me: do we ship a v0.1 to npm now, or hold for 0.2 with the Figma library + live playgrounds?

Arguments for now:

  • Every additional week the repo sits private, momentum bleeds.
  • People can install + use it today; the gaps are around discoverability and design partnership, not the library.
  • A real release forces real feedback. Internal use ≠ external use.

Arguments for holding:

  • A first release that lacks live demos in docs reads as “promising but incomplete.”
  • The benchmark suite would be much more credible if shipped with the first release.

Tentative call: ship a 0.1.0 next Sunday (June 1) with a clear “this is early; here’s what’s coming in 0.2” header. Live demos and the benchmark land in the 0.2 release on or around June 30.

What I want feedback on

  • The strong NOs in MANIFESTO.md — are any too strong? Specifically, “No CSS-in-JS” feels right to me but I expect pushback.
  • The DNA URL share — does it work for you? Does the theme name feel arbitrary?
  • Any component you tried to use and went “oh, that doesn’t exist”? Add it to GOOD_FIRST_ISSUES.md.

Next two weeks

  • Live component playground in apps/docs (1 day per primitive × 20 primitives = the focus).
  • Form recipe — got a draft; needs the actual react-hook-form Field wrapper polished.
  • Showroom (the place to find every component visually) needs the three new components added.
  • One day on the launch trailer GIF.

— Wayne