valaxy-theme

# Valaxy theme authoring Turn the user's visual direction into a source-distributed theme and a working demo. Read [the theme contract](references/theme-contract.md) before changing rendering or package entrypoints. Read [the AK UI recipe](references/ak-ui.md) only when the user chooses AK UI or an Arknights-inspired theme. ## Skill and brief have different roles This Skill supplies reusable framework knowledge and the development/verification workflow. The user's brief supplies this task's theme name, audience, visual direction, required pages and constraints. A brief generated by the docs is ordinary task input: preserve its choices, without treating its preset as a mandatory theme architecture. Do not ask the user for a second, full engineering prompt when this Skill is available. For a new theme, establish the package/demo baseline and implement the reading experience. For an existing theme, inspect the requested change and preserve unrelated behavior, package identity and content. Do not re-run initialization or regenerate the whole theme for an iteration. Scale validation to what changed: style edits need affected-page checks; rendering, dependencies or exports need the corresponding build/package checks. ## Establish the baseline - Inspect the current workspace, applicable AGENTS.md, package scripts, installed Valaxy version and exported types. Adapt an existing theme when that is the request. - For a new independent theme, use https://github.com/valaxyjs/valaxy-theme-starter in a new directory. Its `theme/` package and `demo/` consumer are the starting point. If `theme:init` exists, run `pnpm theme:init <name>` inside the new workspace, adding `--owner <owner>` only when the repository owner is known; otherwise update package references and `theme` configuration together. Run `pnpm install` after renaming. - Keep published examples portable. Do not leave absolute paths, developer-checkout symlinks or `link:` dependencies in their manifests or lockfiles. - Confirm an unfamiliar API against the installed package or https://valaxy.site/themes/write. Valaxy versions differ; a plausible API name is not evidence that it exists. ## Translate the design brief Identify the blog audience, reading priorities, palette, typography and one distinctive structural idea. Preserve an explicitly requested style. If the brief is sparse, choose reasonable defaults and state them; ask only for a missing decision that materially changes the result. Keep site identity and article content configurable. Use actual post metadata in archive counts, dates, tags and navigation. Build the reading experience alongside the homepage: a long article with headings, code, quotes, links, a table and an image must remain comfortable on mobile. Separate the shell/navigation, homepage, post list, article frame and optional outline into focused Vue components. Use Vue 3 `<script setup lang="ts">`; prefer native interactions and the project's existing primitives. Expose only implemented theme options with types and defaults. ## Implement and validate Follow the installed framework's `ValaxyMain` / `ValaxyMd`, layout and slot contracts. Keep browser-only effects in mounted/client-guarded code. Use Valaxy's post APIs rather than maintaining a separate hard-coded post list. Never include drafts in a production archive merely to make a demo look populated. Inspect real package scripts for lint, type checking, tests and the demo build. For a new theme or rendering change, run an SSG build explicitly (`valaxy build --ssg` or a script that includes it); a successful SPA build is not SSG verification. Generate the demo’s Valaxy declarations before standalone type checking when required by the starter. Inspect desktop and mobile pages, internal navigation, article rendering, appearance switching, keyboard focus and empty states. Check console/hydration errors. Test a non-root Vite base when the theme is intended for subdirectory hosting. Build success alone does not verify appearance. Pack the theme and verify its exported entries and required source directories. For changes to dependencies or exports, install the archive in a fresh consumer and build it. Update the README with supported layouts/options, development commands and actual compatibility. Report what was verified and what remains incomplete. Generating a theme does not itself publish it to npm or deploy a site.