151 lines
5.3 KiB
Markdown
151 lines
5.3 KiB
Markdown
# Glitch Component Standard
|
|
|
|
This workspace exists to produce standalone Vite mini-games for Glitch University that can be developed locally, bundled independently, copied into the host application, and registered as unlockable learning components.
|
|
|
|
The goal of the standard is simple:
|
|
|
|
- make every new component start from the same reliable contract
|
|
- keep host integration predictable
|
|
- keep visual language coherent without flattening creativity
|
|
- reduce the amount of handwork required after `npm run build`
|
|
|
|
## Canonical References
|
|
|
|
Use these files as the source of truth when creating or reviewing a component:
|
|
|
|
- Contract: `standards/glitch-component/contract.ts`
|
|
- Dev theme tokens: `standards/glitch-component/dev-theme.css`
|
|
- Scaffold template: `templates/react-vite-glitch-component/`
|
|
- Workspace tooling: `scripts/new-glitch-component.mjs`, `scripts/glitch-components.mjs`
|
|
|
|
`glitch_lightlane` and `glitch_chess_analogy` are the current reference components for more recent build and interaction quality. Older folders should be treated as legacy unless they are brought up to this standard.
|
|
|
|
## Naming
|
|
|
|
Each component has three related names:
|
|
|
|
- Component id: kebab-case, used in metadata and manifests. Example: `chess-analogy`
|
|
- Folder name: `glitch_` plus the component id converted to snake case. Example: `glitch_chess_analogy`
|
|
- Package name: `@glitch-components/<component-id>`
|
|
|
|
This keeps host-facing ids clean while preserving the existing workspace convention of `glitch_*` folders.
|
|
|
|
## Required Files
|
|
|
|
Every new component should include:
|
|
|
|
- `glitch.manifest.json`
|
|
- `README.md`
|
|
- `package.json`
|
|
- `tsconfig.json`
|
|
- `vite.config.ts`
|
|
- `index.html`
|
|
- `src/index.tsx`
|
|
- `src/Component.tsx`
|
|
- `src/types.ts`
|
|
- `src/styles.module.css`
|
|
- `src/dev.tsx`
|
|
- `src/dev-theme.css`
|
|
- `src/vite-env.d.ts`
|
|
|
|
## Component Contract
|
|
|
|
Use the contract defined in `standards/glitch-component/contract.ts`.
|
|
|
|
The important rules are:
|
|
|
|
- `src/index.tsx` must export `default` and `metadata`
|
|
- `metadata.defaultParams` must produce a working component
|
|
- runtime configuration must come from `config.params`
|
|
- `onComplete` is the completion handshake back to the host
|
|
- `onProgress` is optional but should be used when the learner advances through a clear sequence
|
|
- `host` is optional and should be used for things like sound and host events
|
|
|
|
Completion must follow the host callback contract:
|
|
|
|
- a component is not considered complete just because it navigates to a final screen or shows a success state
|
|
- the final completion action must call `onComplete(...)` with a success payload so the host pipeline can unlock, award, close, or route correctly
|
|
- if the component has a guided sequence, `onProgress(...)` should be emitted as the learner advances through meaningful milestones
|
|
- local buttons like `Finish`, `Complete Challenge`, or `Take the Glitch Gate` should be treated as the trigger point for `onComplete(...)`
|
|
|
|
Reference pattern:
|
|
|
|
- local UI reaches final state
|
|
- learner presses the final action
|
|
- component calls `onComplete({ success: true, ... })`
|
|
- host handles the rest of the pipeline
|
|
|
|
## Styling Rules
|
|
|
|
Creativity should live in composition, motion, layout, illustration, and interaction design. Integration rules should not live there.
|
|
|
|
These styling rules are non-negotiable:
|
|
|
|
- Packaged component styles stay scoped with CSS Modules
|
|
- Use host tokens such as `--color-*`, `--font-*`, `--spacing-*`
|
|
- If component code needs local aliases, map them from host tokens inside the component root
|
|
- Dev-only theme variables belong in `src/dev-theme.css`
|
|
- Production entrypoints must not import dev-only styles
|
|
- Do not import remote fonts inside packaged component CSS
|
|
- Avoid global resets inside the package bundle
|
|
|
|
## Packaging Rules
|
|
|
|
- Build in Vite library mode from `src/index.tsx`
|
|
- Inject component CSS with `vite-plugin-css-injected-by-js`
|
|
- Keep `react`, `react-dom`, and `react/jsx-runtime` external
|
|
- Add Three/R3F externals only when the component actually uses them
|
|
- Sourcemaps stay enabled
|
|
|
|
## Manifest Rules
|
|
|
|
Each component should include `glitch.manifest.json` with:
|
|
|
|
- `componentId`
|
|
- `displayName`
|
|
- `version`
|
|
- `folderName`
|
|
- `packageName`
|
|
- `entry`
|
|
- `source`
|
|
- `tags`
|
|
|
|
The manifest is the handoff surface between build output and host integration. It should be generated or updated with the component, not reconstructed later by memory.
|
|
|
|
## Workspace Commands
|
|
|
|
Run these from the workspace root:
|
|
|
|
- `npm run glitch:new -- <component-id> --title "Display Name"`
|
|
- `npm run glitch:validate`
|
|
- `npm run glitch:build`
|
|
- `npm run glitch:release`
|
|
|
|
Compatibility wrappers remain available:
|
|
|
|
- `./build.sh`
|
|
- `./copy.sh`
|
|
- `./dev.sh <folder-name>`
|
|
|
|
## Release Flow
|
|
|
|
1. Scaffold from the canonical template.
|
|
2. Build the component locally with `npm run build`.
|
|
3. Validate the workspace standard with `npm run glitch:validate`.
|
|
4. Release with `npm run glitch:release`.
|
|
5. Import the copied manifest into the Glitch University registration step instead of hand-reconstructing metadata.
|
|
|
|
## Legacy Cleanup Policy
|
|
|
|
Not every older component needs to be rewritten immediately.
|
|
|
|
When touching a legacy component:
|
|
|
|
- align it to the shared contract
|
|
- remove dev-only styles from production entrypoints
|
|
- add a manifest
|
|
- add or refresh the README
|
|
- move toward host token usage
|
|
|
|
That way cleanup happens continuously without blocking new game ideas.
|