@noobsociety/nsds 0.1.2 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/CHANGELOG.md +56 -7
  2. package/CONTRIBUTING.md +89 -10
  3. package/README.md +100 -195
  4. package/dist/components/hud/HUDBar.d.ts +17 -0
  5. package/dist/components/hud/HUDDivider.d.ts +11 -0
  6. package/dist/components/hud/HUDLabel.d.ts +17 -0
  7. package/dist/components/icons/RPGIcon.d.ts +42 -0
  8. package/dist/index.cjs +1 -0
  9. package/dist/index.d.ts +18 -0
  10. package/dist/index.js +1984 -0
  11. package/{styles.css → dist/styles.css} +1 -0
  12. package/dist/tailwind/package.json +1 -0
  13. package/dist/tailwind/preset.js +144 -0
  14. package/{tokens → dist/tokens}/colors.css +25 -19
  15. package/dist/tokens/hud.css +133 -0
  16. package/{tokens → dist/tokens}/motion.css +9 -9
  17. package/{tokens → dist/tokens}/spacing.css +9 -16
  18. package/{tokens → dist/tokens}/typography.css +2 -2
  19. package/package.json +43 -62
  20. package/SKILL.md +0 -18
  21. package/assets/bg.png +0 -0
  22. package/assets/bloop.png +0 -0
  23. package/assets/hero.png +0 -0
  24. package/assets/lamp.png +0 -0
  25. package/assets/logo.png +0 -0
  26. package/assets/mailbox.png +0 -0
  27. package/assets/plaza.png +0 -0
  28. package/assets/prickle.png +0 -0
  29. package/assets/sign.png +0 -0
  30. package/components/buttons/Button.js +0 -55
  31. package/components/buttons/Button.prompt.md +0 -22
  32. package/components/buttons/buttons.card.html +0 -24
  33. package/components/cards/FeatureCard.js +0 -36
  34. package/components/cards/FeatureCard.prompt.md +0 -17
  35. package/components/cards/QuestCard.js +0 -27
  36. package/components/cards/QuestCard.prompt.md +0 -19
  37. package/components/cards/cards.card.html +0 -54
  38. package/components/navigation/SectionArrow.js +0 -28
  39. package/components/navigation/navigation.card.html +0 -29
  40. package/components/react/index.d.ts +0 -11
  41. package/components/react/index.js +0 -4
  42. package/components/shared/styles.js +0 -22
  43. package/guidelines/brand.card.html +0 -41
  44. package/guidelines/colors.card.html +0 -43
  45. package/guidelines/motion.card.html +0 -24
  46. package/guidelines/pixel-accents.card.html +0 -50
  47. package/guidelines/radii-shadows.card.html +0 -28
  48. package/guidelines/semantic-colors.card.html +0 -30
  49. package/guidelines/spacing.card.html +0 -53
  50. package/guidelines/sprites.card.html +0 -22
  51. package/guidelines/type.card.html +0 -24
  52. package/index.d.ts +0 -1
  53. package/index.js +0 -1
  54. package/mui-theme/ThemeProvider.js +0 -14
  55. package/mui-theme/ThemeProvider.tsx +0 -20
  56. package/mui-theme/examples/FeatureCard.tsx +0 -52
  57. package/mui-theme/examples/QuestStatusChip.tsx +0 -41
  58. package/mui-theme/examples/SectionHeader.tsx +0 -44
  59. package/mui-theme/index.d.ts +0 -49
  60. package/mui-theme/index.js +0 -2
  61. package/mui-theme/index.ts +0 -2
  62. package/mui-theme/preview.dc.html +0 -195
  63. package/mui-theme/support.js +0 -1513
  64. package/mui-theme/theme.js +0 -594
  65. package/mui-theme/theme.ts +0 -604
  66. package/references/noobsociety-monokai.dc.html +0 -360
  67. package/support.js +0 -1513
  68. package/ui-kits/homepage/index.html +0 -319
  69. /package/{components → dist/components}/buttons/Button.d.ts +0 -0
  70. /package/{components → dist/components}/cards/FeatureCard.d.ts +0 -0
  71. /package/{components → dist/components}/cards/QuestCard.d.ts +0 -0
  72. /package/{components → dist/components}/navigation/SectionArrow.d.ts +0 -0
  73. /package/{components → dist/components}/primitives.css +0 -0
  74. /package/{tokens → dist/tokens}/base.css +0 -0
package/CHANGELOG.md CHANGED
@@ -2,7 +2,50 @@
2
2
 
3
3
  All notable changes to NSDS are documented here.
4
4
 
5
- ## 0.1.2 - 2026-06-18
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.2.1] - 2026-06-20
10
+
11
+ ### Added
12
+
13
+ - Project README structure for install, usage, package exports, development, release, and license guidance.
14
+ - Changesets configuration and release scripts for version intent and publishing.
15
+ - Storybook configuration and component stories for the public React package surface.
16
+ - Release workflow for Changesets version pull requests and npm publishing.
17
+
18
+ ### Changed
19
+
20
+ - Contribution guidance now documents SemVer, changelog, release, component documentation, and license expectations.
21
+ - Public documentation now describes only the package source and published package surface.
22
+
23
+ ### Removed
24
+
25
+ - Design-source and prototype artifacts from the public repository tree.
26
+
27
+ ## [0.2.0] - 2026-06-20
28
+
29
+ ### Added
30
+
31
+ - Tailwind preset export for mapping `--ns-*` design tokens into utility classes.
32
+ - HUD token file and HUD React primitives for game-layer UI.
33
+ - RPG icon React component and icon catalog support.
34
+
35
+ ### Changed
36
+
37
+ - Package output now builds from JSX source into `dist/` with ESM, CommonJS, TypeScript declarations, CSS, tokens, primitives, and Tailwind preset files.
38
+ - Public package surface is React, Tailwind, CSS tokens, and primitives only.
39
+ - Canonical component runtime sources now use `.jsx` files.
40
+ - README package exports and repo layout now match the published package boundary.
41
+
42
+ ### Removed
43
+
44
+ - Legacy theme package surface, dependencies, docs, tests, and source files.
45
+ - Duplicate compiled component runtime source files.
46
+ - Superseded `ui-kits/` homepage path.
47
+
48
+ ## [0.1.2] - 2026-06-18
6
49
 
7
50
  ### Added
8
51
 
@@ -11,25 +54,31 @@ All notable changes to NSDS are documented here.
11
54
  - Repository contribution, security, issue, pull request, and dependency update templates.
12
55
  - Package validation scripts for exports, required files, and publish hygiene.
13
56
  - React smoke tests for the public component entry points.
14
- - JavaScript runtime and TypeScript declarations for `@noobsociety/nsds/mui`.
15
57
  - TypeScript smoke validation for consumer-facing package imports.
16
- - Prioritized README roadmap and reference standards for documentation, changelog, versioning, release, and component documentation workflows.
58
+ - Tailwind preset export for token-mapped utility classes.
59
+ - Prioritized README roadmap and documentation, changelog, versioning, release, and component documentation workflows.
17
60
 
18
61
  ### Changed
19
62
 
20
63
  - Updated README language for the public npm package and repository.
21
64
  - Documented the TypeScript and testing roadmap.
22
- - Pointed the public MUI export at package-ready JavaScript instead of raw TypeScript source.
23
65
 
24
- ## 0.1.1 - 2026-06-18
66
+ ## [0.1.1] - 2026-06-18
25
67
 
26
68
  ### Changed
27
69
 
28
70
  - Published the package as `@noobsociety/nsds`.
29
71
  - Updated repository metadata for the public NSDS package.
30
72
 
31
- ## 0.1.0 - 2026-06-18
73
+ ## [0.1.0] - 2026-06-18
32
74
 
33
75
  ### Added
34
76
 
35
- - Initial NSDS package with tokens, CSS primitives, React components, MUI theme source, assets, guidelines, references, and UI kits.
77
+ - Initial NSDS package with tokens, CSS primitives, React components, and Tailwind support.
78
+
79
+ [Unreleased]: https://github.com/noobsociety/nsds/compare/v0.2.1...HEAD
80
+ [0.2.1]: https://github.com/noobsociety/nsds/compare/v0.2.0...v0.2.1
81
+ [0.2.0]: https://github.com/noobsociety/nsds/compare/v0.1.2...v0.2.0
82
+ [0.1.2]: https://github.com/noobsociety/nsds/compare/v0.1.1...v0.1.2
83
+ [0.1.1]: https://github.com/noobsociety/nsds/compare/v0.1.0...v0.1.1
84
+ [0.1.0]: https://github.com/noobsociety/nsds/releases/tag/v0.1.0
package/CONTRIBUTING.md CHANGED
@@ -1,34 +1,113 @@
1
1
  # Contributing
2
2
 
3
- NSDS is the NoobSociety Design System. Changes should keep the package small, reusable, and direct.
3
+ NSDS is the NoobSociety Design System. Changes should keep the package small, reusable, direct, and Tailwind-first.
4
4
 
5
- ## Local Setup
5
+ ## Local setup
6
+
7
+ Use Node.js 22 or newer.
6
8
 
7
9
  ```bash
8
10
  npm install
9
11
  npm run check
10
12
  ```
11
13
 
12
- ## Change Guidelines
14
+ Run Storybook while changing components:
15
+
16
+ ```bash
17
+ npm run storybook
18
+ ```
19
+
20
+ ## Change guidelines
13
21
 
14
22
  - Keep package exports stable unless the release is intentionally breaking.
15
23
  - Prefer CSS tokens and shared primitives over one-off styles.
16
24
  - Keep React components small and framework-light.
17
- - Add or update smoke coverage when changing component behavior.
18
- - Use patch versions for metadata, docs, small fixes, and compatibility work.
19
- - Use minor versions for new components, tokens, or larger additive behavior.
25
+ - Add or update Storybook stories when changing public component behavior or props.
26
+ - Add or update smoke coverage when changing import behavior, package exports, or runtime behavior.
27
+ - Keep third-party code and assets license-compatible with MIT.
28
+
29
+ ## Versioning
30
+
31
+ NSDS follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
32
+
33
+ - Patch versions are for docs, metadata, dependency compatibility, bug fixes, and non-breaking visual corrections.
34
+ - Minor versions are for new components, tokens, exports, or additive behavior.
35
+ - Major versions are for breaking public API changes, removed exports, incompatible CSS token changes, or required consumer migration.
36
+
37
+ The package is still pre-1.0, but release intent should still be explicit. If a `0.x` minor release contains a breaking package-boundary change, document the migration clearly in the changelog.
38
+
39
+ ## Changelog
40
+
41
+ `CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
20
42
 
21
- ## Release Checks
43
+ Use these categories when applicable:
22
44
 
23
- Before publishing:
45
+ - `Added`
46
+ - `Changed`
47
+ - `Deprecated`
48
+ - `Removed`
49
+ - `Fixed`
50
+ - `Security`
51
+
52
+ Keep user-facing changes in the changelog. Internal maintenance can stay in the pull request when it has no package or contributor impact.
53
+
54
+ Add unreleased package notes under `## [Unreleased]`. During release, `npm run changeset:version` moves those notes into a dated version section and updates the compare links.
55
+
56
+ ## Changesets
57
+
58
+ Every package-impacting pull request should include a changeset:
59
+
60
+ ```bash
61
+ npm run changeset
62
+ ```
63
+
64
+ Choose the SemVer bump that matches the public impact. Documentation-only changes may skip a changeset when they do not affect the published package behavior.
65
+
66
+ Maintainers prepare release commits with:
67
+
68
+ ```bash
69
+ npm run changeset:version
70
+ ```
71
+
72
+ This command applies the Changesets version plan and updates `CHANGELOG.md` from the `[Unreleased]` section. Open the result as a release pull request.
73
+
74
+ Publishing is handled by the release workflow after the release pull request is merged to `main`, when `NPM_TOKEN` is configured:
75
+
76
+ ```bash
77
+ npm run changeset:publish
78
+ ```
79
+
80
+ ## Component documentation
81
+
82
+ Public React components must have Storybook coverage.
83
+
84
+ ```bash
85
+ npm run storybook
86
+ npm run build:storybook
87
+ ```
88
+
89
+ Stories should show the stable public props, common variants, disabled or edge states when relevant, and realistic token-backed styling. Avoid documenting private implementation details as API.
90
+
91
+ ## Release checks
92
+
93
+ Before merging a package-impacting change:
24
94
 
25
95
  ```bash
26
96
  npm run check
97
+ npm run build:storybook
27
98
  npm run release:dry-run
28
99
  ```
29
100
 
30
- Publish with an npm one-time password when required:
101
+ Before publishing manually:
31
102
 
32
103
  ```bash
33
- npm publish --otp=123456
104
+ npm run check
105
+ npm run release:dry-run
106
+ npm run changeset:publish
34
107
  ```
108
+
109
+ ## License guidance
110
+
111
+ NSDS uses the [MIT License](./LICENSE), selected from [Choose a License](https://choosealicense.com/licenses/mit/).
112
+
113
+ New code, images, fonts, and documentation must be original, owned by NoobSociety, or compatible with MIT redistribution. When adding third-party material, document its source and license in the pull request.
package/README.md CHANGED
@@ -1,263 +1,168 @@
1
1
  # NoobSociety Design System
2
2
 
3
- [![CI](https://github.com/noobsociety/nsds/actions/workflows/ci.yml/badge.svg)](https://github.com/noobsociety/nsds/actions/workflows/ci.yml)
4
- [![npm](https://img.shields.io/npm/v/@noobsociety/nsds.svg)](https://www.npmjs.com/package/@noobsociety/nsds)
5
- [![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f.svg)](LICENSE)
3
+ Reusable design tokens, CSS primitives, Tailwind preset, and pixel-art React components for NoobSociety.
6
4
 
7
- **NSDS** is the reusable NoobSociety Design System package: design tokens, CSS primitives, React components, MUI theme runtime, pixel assets, and reference UI kits for building NoobSociety interfaces.
5
+ NSDS is Tailwind-first and token-driven. It ships the public package surface needed by product apps: React components, CSS tokens, primitives, and a Tailwind preset.
8
6
 
9
- The system is built around a simple rule: **Monokai colors are semantic foregrounds, dark surfaces are the world canvas.**
7
+ ## Contents
10
8
 
11
- ## Install
9
+ - [Install](#install)
10
+ - [Quick start](#quick-start)
11
+ - [Package exports](#package-exports)
12
+ - [Components](#components)
13
+ - [Repository layout](#repository-layout)
14
+ - [Development](#development)
15
+ - [Versioning and releases](#versioning-and-releases)
16
+ - [License](#license)
12
17
 
13
- Install from npm:
18
+ ## Install
14
19
 
15
20
  ```bash
16
21
  npm install @noobsociety/nsds
17
22
  ```
18
23
 
19
- Use a local workspace package while developing against this repository:
24
+ Peer dependencies:
20
25
 
21
- ```json
22
- {
23
- "dependencies": {
24
- "@noobsociety/nsds": "file:../design-system"
25
- }
26
- }
26
+ ```bash
27
+ npm install react react-dom
27
28
  ```
28
29
 
29
- ## Usage
30
+ ## Quick start
30
31
 
31
- Import the full CSS entry when you want tokens, base styles, and shared primitives:
32
+ Import the CSS entry once in your app:
32
33
 
33
- ```js
34
- import '@noobsociety/nsds/styles.css';
34
+ ```tsx
35
+ import '@noobsociety/nsds/styles';
35
36
  ```
36
37
 
37
- Use React components with the CSS entry:
38
+ Use React components from the package root:
38
39
 
39
- ```jsx
40
- import '@noobsociety/nsds/styles.css';
41
- import { Button, FeatureCard, QuestCard, SectionArrow } from '@noobsociety/nsds/react';
40
+ ```tsx
41
+ import { Button, FeatureCard, HUDBar, RPGIcon } from '@noobsociety/nsds';
42
42
 
43
43
  export function Example() {
44
44
  return (
45
- <Button href="https://noobsociety.com">▶ Enter the world</Button>
45
+ <FeatureCard
46
+ icon={<RPGIcon name="sword" />}
47
+ title="World UI"
48
+ body="Pixel-art components mapped to NSDS tokens."
49
+ tag="Live"
50
+ />
46
51
  );
47
52
  }
48
53
  ```
49
54
 
50
- Use individual token or asset files when a project only needs part of the system:
55
+ Use the Tailwind preset in product apps:
51
56
 
52
57
  ```js
53
- import '@noobsociety/nsds/tokens/colors.css';
54
- import logoUrl from '@noobsociety/nsds/assets/logo.png';
55
- ```
56
-
57
- Install MUI peer dependencies before using the MUI entry:
58
-
59
- ```bash
60
- npm install @mui/material @emotion/react @emotion/styled
61
- ```
62
-
63
- Use the MUI theme in app shells:
58
+ import nsdsPreset from '@noobsociety/nsds/tailwind';
64
59
 
65
- ```jsx
66
- import { NSThemeProvider, theme, NS } from '@noobsociety/nsds/mui';
60
+ export default {
61
+ presets: [nsdsPreset],
62
+ content: ['./src/**/*.{js,jsx,ts,tsx}'],
63
+ };
67
64
  ```
68
65
 
69
- The MUI entry ships JavaScript runtime files and TypeScript declarations. The original TypeScript source stays in `mui-theme/` for reference and future migration work.
70
-
71
- ## Package Exports
66
+ ## Package exports
72
67
 
73
68
  | Export | Purpose |
74
- |---|---|
75
- | `@noobsociety/nsds` | Root React component entry |
76
- | `@noobsociety/nsds/react` | React components |
77
- | `@noobsociety/nsds/mui` | MUI theme runtime and types |
78
- | `@noobsociety/nsds/styles.css` | Full CSS entry |
79
- | `@noobsociety/nsds/package.json` | Package metadata |
80
- | `@noobsociety/nsds/components/primitives.css` | Component primitive classes only |
69
+ | --- | --- |
70
+ | `@noobsociety/nsds` | React components |
71
+ | `@noobsociety/nsds/react` | Compatibility alias for React components |
72
+ | `@noobsociety/nsds/tailwind` | Tailwind preset mapped to `--ns-*` tokens |
73
+ | `@noobsociety/nsds/styles` | Full CSS entry |
74
+ | `@noobsociety/nsds/styles.css` | CSS entry compatibility alias |
81
75
  | `@noobsociety/nsds/tokens/*` | Individual token CSS files |
82
- | `@noobsociety/nsds/assets/*` | Pixel assets and brand images |
83
- | `@noobsociety/nsds/guidelines/*` | Specimen cards |
84
- | `@noobsociety/nsds/references/*` | Polished `.dc.html` references |
85
- | `@noobsociety/nsds/ui-kits/*` | Complete UI kits |
86
-
87
- ## Design Model
88
-
89
- ### Monokai Foregrounds
90
-
91
- Monokai colors are used on top of the canvas: text, icons, borders, buttons, status pills, accents, and interaction states. Each hue has one semantic role. Do not reassign a color to a different role.
92
-
93
- | Token | Hex | Role |
94
- |---|---|---|
95
- | `--ns-ink` | `#f8f8f2` | Primary text |
96
- | `--ns-ink-faint` | `#75715e` | Muted text, captions, placeholders |
97
- | `--ns-gold` | `#e6db74` | Primary accent, CTAs, eyebrows, active nav |
98
- | `--ns-green` | `#a6e22e` | Success, live state, `HOLDS` |
99
- | `--ns-orange` | `#fd971f` | In progress, active state, `BUILDING` |
100
- | `--ns-cyan` | `#66d9e8` | Planned, info, links |
101
- | `--ns-pink` | `#f92672` | Highlight, danger, high-energy accent |
102
- | `--ns-purple` | `#ae81ff` | Decorative, personal, tertiary accent |
103
-
104
- ### Dark Canvas
105
-
106
- Dark colors sit underneath the Monokai foregrounds. They define the world canvas, raised surfaces, headers, cards, and overlays.
107
-
108
- | Token | Hex | Role |
109
- |---|---|---|
110
- | `--ns-bg-0` | `#1a1a16` | Deepest surface: footer, sidebar, backdrop |
111
- | `--ns-bg-1` | `#272822` | Page base |
112
- | `--ns-bg-2` | `#32332b` | Raised surface, icon slot, input fill |
113
- | `--ns-glass` | `rgba(30,31,26,.88)` | Card and header glass |
114
-
115
- The default experience is dark. Do not introduce a light-mode default unless it is intentionally designed as a separate theme.
116
-
117
- ## Content Rules
76
+ | `@noobsociety/nsds/primitives` | Component primitive CSS |
77
+ | `@noobsociety/nsds/components/primitives.css` | Component primitive CSS compatibility alias |
118
78
 
119
- - **Voice:** Direct, honest, playful. Not corporate.
120
- - **Casing:** Sentence case. Title case only for names and proper nouns.
121
- - **Length:** Short sentences. One idea per sentence.
122
- - **Emoji:** Avoid emoji. Use pixel accents such as `✦`, `▶`, `★`, `✓`, and `◌` when useful.
123
- - **Numbers:** Use numbers only when they are specific and meaningful.
124
- - **Perspective:** Speak directly. Avoid abstract phrases like "users" and "visitors" when "you" is clearer.
79
+ The npm package ships `dist/` plus package metadata, changelog, contribution guidance, security policy, and license.
125
80
 
126
- ## Visual Rules
81
+ ## Components
127
82
 
128
- ### Typography
83
+ Public React components:
129
84
 
130
- - `Press Start 2P`: wordmark, buttons, status pills, card labels, section accents, and pixel UI.
131
- - `Inter`: body copy, navigation, subtitles, paragraphs, and dense information.
132
- - Pixel text must use generous line height. Keep it short.
133
- - Body copy should stay readable and calm.
85
+ - `Button`
86
+ - `FeatureCard`
87
+ - `QuestCard`
88
+ - `HUDBar`
89
+ - `HUDDivider`
90
+ - `HUDLabel`
91
+ - `RPGIcon`
92
+ - `HUDIcon`
93
+ - `SectionArrow`
134
94
 
135
- ### Layout
95
+ Run Storybook for component documentation:
136
96
 
137
- - Base spacing follows a 4px grid.
138
- - Default container width is `1080px`.
139
- - Full sections use `min-height: calc(100svh - var(--ns-header-h))`.
140
- - Responsive baseline: `375x667` portrait and `667x375` landscape.
97
+ ```bash
98
+ npm run storybook
99
+ ```
141
100
 
142
- ### Cards
101
+ Build static Storybook documentation:
143
102
 
144
- - Use glass surfaces with `10px` radius.
145
- - Do not add resting drop shadows.
146
- - Use hover elevation only: `translateY(-4px)` plus the card hover shadow.
103
+ ```bash
104
+ npm run build:storybook
105
+ ```
147
106
 
148
- ### Buttons
107
+ ## Repository layout
149
108
 
150
- - Primary `play` buttons use gold fill, dark text, a gold border, and a physical press shadow.
151
- - `ghost` buttons stay transparent until hover.
152
- - Buttons use `Press Start 2P`.
109
+ | Path | Purpose |
110
+ | --- | --- |
111
+ | `styles.css` | Public CSS entry point |
112
+ | `tokens/` | CSS custom properties for color, type, spacing, motion, and HUD values |
113
+ | `components/` | React components, TypeScript declarations, primitive CSS, and stories |
114
+ | `tailwind/` | Tailwind preset source |
153
115
 
154
- ### Motion
116
+ ## Development
155
117
 
156
- - Keep interaction motion fast: `150ms ease-out`.
157
- - Keep decorative motion subtle.
158
- - Respect reduced motion; `ns-*` animations are disabled under `prefers-reduced-motion: reduce`.
118
+ Use Node.js 22 or newer.
159
119
 
160
- ## Component Notes
120
+ ```bash
121
+ npm install
122
+ npm run check
123
+ ```
161
124
 
162
- ### Button
125
+ Common scripts:
163
126
 
164
- Use for primary and secondary actions.
127
+ | Script | Purpose |
128
+ | --- | --- |
129
+ | `npm run build` | Build the package into `dist/` |
130
+ | `npm run check` | Build, validate package metadata, type-check, and smoke-test imports |
131
+ | `npm run storybook` | Start component documentation locally |
132
+ | `npm run build:storybook` | Build static component documentation |
133
+ | `npm run release:dry-run` | Preview the npm package contents |
134
+ | `npm run changeset` | Add a release note and version intent |
165
135
 
166
- ```jsx
167
- <Button variant="play" href="https://noobsociety.com">▶ Enter the world</Button>
168
- <Button variant="ghost" href="https://github.com/noobsociety">★ Star on GitHub</Button>
169
- <Button variant="play" size="sm">▶ Play</Button>
170
- ```
136
+ ## Versioning and releases
171
137
 
172
- ### FeatureCard
138
+ NSDS follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). All release notes use [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories.
173
139
 
174
- Use for short feature grids. Render inside a `ul`.
140
+ Use Changesets for release intent:
175
141
 
176
- ```jsx
177
- <FeatureCard
178
- icon={<CursorIcon />}
179
- title="The site is a world"
180
- body="Pages are maps, links are interactables."
181
- tag="Spatial"
182
- />
142
+ ```bash
143
+ npm run changeset
183
144
  ```
184
145
 
185
- ### QuestCard
146
+ Maintainers create release commits with:
186
147
 
187
- Use for gate or roadmap states. Render inside an `ol`.
188
-
189
- ```jsx
190
- <QuestCard
191
- gate={3}
192
- title="Objects"
193
- body="In-space sections open content."
194
- status="active"
195
- />
148
+ ```bash
149
+ npm run changeset:version
196
150
  ```
197
151
 
198
- Status mapping:
199
-
200
- | Status | Label | Color |
201
- |---|---|---|
202
- | `done` | `HOLDS` | `--ns-green` |
203
- | `active` | `BUILDING` | `--ns-orange` |
204
- | `planned` | `PLANNED` | `--ns-cyan` |
205
- | `locked` | `LATER` | `--ns-ink-faint` |
206
-
207
- ## File Index
208
-
209
- | Path | Contents |
210
- |---|---|
211
- | `package.json` | Package metadata, exports, peer dependencies |
212
- | `index.js` / `index.d.ts` | Root React component entry point |
213
- | `styles.css` | Global CSS entry point |
214
- | `support.js` | Runtime support for root `.dc.html` references |
215
- | `tokens/` | Color, typography, spacing, motion, and base CSS tokens |
216
- | `components/primitives.css` | Shared CSS primitives |
217
- | `components/react/` | Public React component barrel export |
218
- | `components/buttons/` | Button component, types, prompt, specimen |
219
- | `components/cards/` | FeatureCard and QuestCard components, types, prompts, specimens |
220
- | `components/navigation/` | SectionArrow component, types, specimen |
221
- | `mui-theme/` | MUI theme runtime, TypeScript source, and examples |
222
- | `assets/` | Logo, sprites, and world imagery |
223
- | `guidelines/` | Visual specimen cards |
224
- | `references/` | Polished `.dc.html` references |
225
- | `ui-kits/` | Complete UI kits |
226
- | `SKILL.md` | Agent skill definition |
152
+ That command applies Changesets version bumps and promotes the current `[Unreleased]` changelog entries into a dated release section.
227
153
 
228
- ## Development
154
+ Open and merge the version commit as a normal release pull request. The release workflow publishes from `main` when the package version is not already on npm and `NPM_TOKEN` is configured.
229
155
 
230
- Run the package checks before publishing:
156
+ Manual publishing remains available for maintainers after the version commit is prepared:
231
157
 
232
158
  ```bash
233
- npm install
234
159
  npm run check
235
160
  npm run release:dry-run
161
+ npm run changeset:publish
236
162
  ```
237
163
 
238
- Use patch versions for public package metadata or documentation polish. Use minor versions for new components, tokens, or breaking-adjacent behavior.
239
-
240
- ## Roadmap
241
-
242
- Priority order:
243
-
244
- 1. Move the current JavaScript runtime to first-class TypeScript source with generated JavaScript and declaration output.
245
- 2. Add component tests for class names, variants, invalid props, and accessibility attributes.
246
- 3. Add package linting for npm exports, types, and install behavior.
247
- 4. Add component documentation with live examples.
248
- 5. Add visual regression coverage for specimen cards and UI kits.
249
-
250
- ## Reference Standards
251
-
252
- - README quality: [Make a README](https://www.makeareadme.com/)
253
- - Changelog format: [Keep a Changelog](https://keepachangelog.com/)
254
- - Versioning: [Semantic Versioning](https://semver.org/)
255
- - Release workflow: [Changesets](https://github.com/changesets/changesets)
256
- - Component documentation: [Storybook](https://storybook.js.org/)
257
- - License guidance: [Choose a License](https://choosealicense.com/)
258
-
259
- ## Repository
164
+ ## License
260
165
 
261
- Source repository: `https://github.com/noobsociety/nsds`
166
+ NSDS is released under the [MIT License](./LICENSE). MIT was selected using the guidance at [Choose a License](https://choosealicense.com/licenses/mit/) because it permits broad reuse with attribution and warranty disclaimers.
262
167
 
263
- The current package is public on npm as `@noobsociety/nsds`. NSDS is released under the MIT license.
168
+ Only add third-party code, assets, or documentation when the license is compatible with MIT and the source is documented in the relevant change.
@@ -0,0 +1,17 @@
1
+ import type * as React from 'react';
2
+
3
+ export interface HUDBarProps {
4
+ /** Current stat value */
5
+ value?: number;
6
+ /** Maximum stat value */
7
+ max?: number;
8
+ /** Bar fill color */
9
+ fillColor?: string;
10
+ /** Bar track color */
11
+ trackColor?: string;
12
+ /** Bar height in px */
13
+ height?: number;
14
+ style?: React.CSSProperties;
15
+ }
16
+
17
+ export declare function HUDBar(props: HUDBarProps): React.ReactElement;
@@ -0,0 +1,11 @@
1
+ import type * as React from 'react';
2
+
3
+ export interface HUDDividerProps {
4
+ /** Vertical by default; use horizontal for a 1px row rule. */
5
+ direction?: 'vertical' | 'horizontal';
6
+ /** Line color */
7
+ color?: string;
8
+ style?: React.CSSProperties;
9
+ }
10
+
11
+ export declare function HUDDivider(props: HUDDividerProps): React.ReactElement;
@@ -0,0 +1,17 @@
1
+ import type * as React from 'react';
2
+
3
+ export interface HUDLabelProps {
4
+ /** Display text */
5
+ text?: string;
6
+ /** Text alignment within the container */
7
+ align?: 'left' | 'center' | 'right';
8
+ /** Uniform scale multiplier applied to fontSize */
9
+ scale?: number;
10
+ /** Text color */
11
+ color?: string;
12
+ /** Base font size in px, before scale */
13
+ fontSize?: number;
14
+ style?: React.CSSProperties;
15
+ }
16
+
17
+ export declare function HUDLabel(props: HUDLabelProps): React.ReactElement;
@@ -0,0 +1,42 @@
1
+ import type * as React from 'react';
2
+
3
+ export type RPGIconWeapon = 'sword' | 'staff' | 'bow' | 'katar' | 'book' | 'hammer';
4
+ export type RPGIconElement = 'neutral' | 'earth' | 'wind' | 'water' | 'fire' | 'light' | 'dark' | 'void';
5
+ export type RPGIconRace = 'human' | 'beast' | 'demon' | 'angel' | 'spirit';
6
+ export type RPGIconSize = 'small' | 'medium' | 'large';
7
+
8
+ export type RPGIconName =
9
+ | RPGIconWeapon
10
+ | RPGIconElement
11
+ | RPGIconRace
12
+ | RPGIconSize;
13
+
14
+ export interface RPGIconProps {
15
+ /**
16
+ * 22 original pixel-art icons across 4 canonical categories:
17
+ *
18
+ * Weapons (6): sword · staff · bow · katar · book · hammer
19
+ * (from game/items/index.ts weapon hand-slot items)
20
+ *
21
+ * Elements (8): neutral · earth · wind · water · fire · light · dark · void
22
+ * (from identity.ts ELEMENTS + ELEMENT_DISPLAY)
23
+ *
24
+ * Races (5): human · beast · demon · angel · spirit
25
+ * (illustrative — race is free text in the game)
26
+ *
27
+ * Sizes (3): small · medium · large
28
+ * (from identity.ts BODY_SIZES)
29
+ */
30
+ name?: RPGIconName;
31
+ /** Rendered size in px (width = height). Default: 22 */
32
+ size?: number;
33
+ style?: React.CSSProperties;
34
+ }
35
+
36
+ export declare function RPGIcon(props: RPGIconProps): React.ReactElement;
37
+
38
+ /** Sorted list of all valid icon names */
39
+ export declare const icons: RPGIconName[];
40
+
41
+ /** @deprecated Use RPGIcon — HUDIcon is kept for backward compatibility */
42
+ export declare const HUDIcon: typeof RPGIcon;