Aurora

Contributing ​

Guides for the most common evolution tasks. For lower-level component, icon, theme-token, and adapter-contract contributions, see packages/aurora/docs/CONTRIBUTING.md in the repo — that doc is the canonical reference for source-level work.

Regenerating the skill ​

Agents read view/ docs directly — editing a doc IS updating the skill, and nothing needs regenerating for content changes. Only two sections of the consumer skill's SKILL.md are derived from docs (the intent → component reach table and the component index, both built from doc frontmatter), and the regenerate-aurora-skill skill refreshes exactly those.

The flow ​

  1. Edit a view/*.md doc. If you only changed body content, you're done — no regen.

  2. If you added/renamed/removed a doc, or changed its blurb:/reach: frontmatter, open a Claude Code session inside packages/aurora/ (the regen skill is scoped here):

    bash
    cd packages/aurora && claude

  3. Prompt: "Run regenerate-aurora-skill."

  4. Claude rebuilds the two derived sections of packages/aurora/skill/SKILL.md from doc frontmatter (phrases copied verbatim, never invented) and prints a gap report — src/components/ families with no doc, docs missing frontmatter.

  5. Review the diff — it touches only those two sections — and commit.

Adding a new component or recipe doc ​

  1. Copy view/_template.md to view/components/<name>.md (or view/recipes/<name>.md) and follow its authoring contract.
  2. Frontmatter must carry title:, blurb: (≤10 words — becomes the component-index line), and reach: (task phrases in the requester's vocabulary — become reach-table rows). Add description: for the VitePress page meta.
  3. Add the doc to the VitePress sidebar in view/.vitepress/config.ts, then run the regen as above.

Never hand-write lists of enumerable code facts (icon names, token allowlists, export lists) in a doc — the skill points at src/ for those; hand-written enumerations are where drift bugs come from.

Releasing a version ​

Aurora is published to GitHub Packages as @scaler-tech/aurora. Releases are tag-driven — pushing an aurora-v* tag triggers the aurora-publish.yml workflow, which builds and publishes.

The flow ​

  1. Bump the version in packages/aurora/package.json — follow semver (patch for fixes, minor for new components/features, major for breaking changes):

    bash
    pnpm --dir packages/aurora version <patch|minor|major>

    Or edit the version field directly.

  2. Commit the bump:

    bash
    git add packages/aurora/package.json
git commit -m "build: aurora v<version>"

  3. Tag the commit and push both the branch and the tag:

    bash
    git tag aurora-v<version>
git push origin <branch> aurora-v<version>

    The tag must match the version in package.json exactly. The publish workflow verifies this and aborts if they diverge.

  4. CI takes over. The aurora-publish.yml workflow runs typecheck, builds aurora, verifies the tag-vs-package.json match, and publishes to GitHub Packages with the repository's GITHUB_TOKEN.

  5. Verify the new version is live:

    bash
    pnpm view @scaler-tech/aurora versions --registry=https://npm.pkg.github.com

Dry-run a publish ​

Before tagging, you can verify the publish step without pushing to the registry. From the GitHub Actions UI:

  1. Go to Actions → Aurora Publish → Run workflow.
  2. Set dry_run: true.
  3. The workflow runs pnpm publish --dry-run instead of the real publish — surfaces any registry, manifest, or build issues before you tag.

Skill regen and releases ​

If your release adds, renames, or removes view/ docs (or changes blurb:/reach: frontmatter), run the regen before tagging so skill/SKILL.md's reach table and component index match the released docs.

Source-level contributions ​

Lower-level changes — adding components, icons, theme tokens, adapter contracts — live at the source-code level and are documented in the repo: