NoobSociety Design System

Reusable design tokens, CSS primitives, Tailwind preset, and pixel-art React components for NoobSociety.

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.

Contents

• Install
• Quick start
• Package exports
• Components
• Documentation
• Repository layout
• Development
• Versioning and releases
• License

Install

npm install @noobsociety/nsds

Peer dependencies:

npm install react react-dom

Quick start

Import the CSS entry once in your app:

import '@noobsociety/nsds/styles';

Use React components from the package root:

import { Button, FeatureCard, HUDBar, RPGIcon } from '@noobsociety/nsds';

export function Example() {
  return (
    <FeatureCard
      icon={<RPGIcon name="sword" />}
      title="World UI"
      body="Pixel-art components mapped to NSDS tokens."
      tag="Live"
    />
  );
}

Use the Tailwind preset in product apps:

import nsdsPreset from '@noobsociety/nsds/tailwind';

export default {
  presets: [nsdsPreset],
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
};

Package exports

| Export | Purpose | | --- | --- | | @noobsociety/nsds | React components | | @noobsociety/nsds/react | Compatibility alias for React components | | @noobsociety/nsds/tailwind | Tailwind preset mapped to --ns-* tokens | | @noobsociety/nsds/styles | Full CSS entry | | @noobsociety/nsds/styles.css | CSS entry compatibility alias | | @noobsociety/nsds/tokens/* | Individual token CSS files | | @noobsociety/nsds/primitives | Component primitive CSS | | @noobsociety/nsds/components/primitives.css | Component primitive CSS compatibility alias |

The npm package ships dist/ plus package metadata, changelog, contribution guidance, security policy, and license.

Components

Public React components:

• Button
• FeatureCard
• QuestCard
• HUDBar
• HUDDivider
• HUDLabel
• RPGIcon
• HUDIcon
• SectionArrow

Run Storybook for component documentation:

npm run storybook

Build static Storybook documentation:

npm run build:storybook

Documentation

Public docs live in docs/ and follow the Diataxis model:

• tutorials for first-time setup
• how-to guides for integration tasks
• reference pages for exports, tokens, classes, and generated API details
• explanation pages for design, accessibility, and versioning decisions

Generate the API reference from TypeScript source:

npm run docs:api

The static landing page lives in site/.

Repository layout

| Path | Purpose | | --- | --- | | styles.css | Public CSS entry point | | tokens/ | CSS custom properties for color, type, spacing, motion, and HUD values | | components/ | TypeScript React source, primitive CSS, and Storybook stories | | tailwind/ | Tailwind preset source | | docs/ | Public documentation and generated API reference | | site/ | Static public landing page | | tests/ | Component and browser-rendered visual checks |

Development

Use Node.js 22 or newer.

npm install
npm run check

Common scripts:

| Script | Purpose | | --- | --- | | npm run build | Build the package into dist/ | | npm run check | Run build, package guards, type checks, tests, and import smoke checks | | npm run check:docs | Regenerate API docs and fail when generated docs drift | | npm run check:exports | Validate npm exports and declaration entry points | | npm run check:install | Install the packed package in a temporary consumer project | | npm run docs:api | Generate markdown API reference from TypeScript source | | npm run storybook | Start component documentation locally | | npm run build:storybook | Build static component documentation | | npm run test:components | Run component behavior tests | | npm run test:visual | Run browser-rendered visual checks | | npm run release:dry-run | Preview the npm package contents | | npm run changeset | Add a release note and version intent |

Versioning and releases

NSDS follows Semantic Versioning. All release notes use Keep a Changelog categories.

Use Changesets for release intent:

npm run changeset

Maintainers create release commits with:

npm run changeset:version

That command applies Changesets version bumps and promotes the current [Unreleased] changelog entries into a dated release section.

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.

Manual publishing remains available for maintainers after the version commit is prepared:

npm run check
npm run release:dry-run
npm run changeset:publish

License

NSDS is released under the MIT License. MIT was selected using the guidance at Choose a License because it permits broad reuse with attribution and warranty disclaimers.

Only add third-party code, assets, or documentation when the license is compatible with MIT and the source is documented in the relevant change.