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 ​

The Aurora consumer skill at packages/aurora/skill/ is a derivative of view/. When you change a doc, regenerate the skill so AI sessions pick up the new guidance.

The flow ​

  1. Edit a view/*.md doc — add a component, change a do/don't, refine a section.

  2. 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 loads the regen methodology, hashes every view/*.md, finds what changed, re-synthesizes only the touched references, updates the manifest, prints a summary.

  5. Review the diff in your editor — it should be minimal (one or two reference files + a manifest entry).

  6. Commit.

Steady-state changes are usually a single reference file plus a manifest entry. The regen is incremental — it does not touch unchanged references.

Adding a new component or pattern doc ​

  1. Create view/components/<name>.md (or view/patterns/<name>.md).
  2. Add the standard frontmatter with both title: and a one-sentence description: — the regenerator uses description: to populate the components/patterns index in the consumer skill's SKILL.md.
  3. Run the regen as above. The new file is classified as added, a fresh reference is synthesized, and the index gets a new row.

When to bump methodology_version ​

The regen skill lives at packages/aurora/.claude/skills/regenerate-aurora-skill/ and its rules are split across four reference files:

  • transform-rules.md — what to keep, strip, normalize
  • voice-and-structure.md — tone, section ordering
  • manifest-format.md — manifest schema
  • incremental-flow.md — the procedure

If you change transform-rules.md or voice-and-structure.md in a way that should retroactively rewrite existing references, bump methodology_version in incremental-flow.md. The next regen detects the mismatch and forces a full rebuild against the new rules.

When to start from scratch ​

Almost never. The bootstrap path kicks in only if packages/aurora/skill/.generation-manifest.json is missing — useful when you nuke skill/ to rebuild everything, which you basically never do. Most evolution happens through incremental regen plus targeted methodology bumps.

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 includes view/ doc changes that affect the skill, regenerate the skill before tagging so the published version's skill/ matches the released docs. The manifest's skill_version field then mirrors the new package version, giving future regens an accurate traceability anchor.

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: