From 18903f930cdb4a7dff28366653b8681ae7f3d454 Mon Sep 17 00:00:00 2001 From: jenstandstad Date: Tue, 24 Mar 2026 15:56:01 +0100 Subject: [PATCH] Adding the glitch_standard to the repo --- GLITCH_COMPONENT_STANDARD.md | 150 +++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 GLITCH_COMPONENT_STANDARD.md diff --git a/GLITCH_COMPONENT_STANDARD.md b/GLITCH_COMPONENT_STANDARD.md new file mode 100644 index 0000000..a0877d1 --- /dev/null +++ b/GLITCH_COMPONENT_STANDARD.md @@ -0,0 +1,150 @@ +# 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/` + +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 -- --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 ` + +## 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.