Ns Ui

What is Ns Ui about?

Ns Ui offers a curated collection of React UI components split into a production‑focused core set (183 components) and a flashy loud set (35 components). Each component is shipped as source code, eliminating runtime package dependencies, and is validated by a Playwright gate that ensures interactive quality and accessibility.

How to use Ns Ui?

1. Direct install with shadcn – In any shadcn‑configured project run:

   npx shadcn add https://design.helpmarq.com/r/<component-name>.json
   

   The command drops components/ui/<name>.tsx into your repo and installs any npm dependencies required by the component.
2. CLI helper – Use the thin CLI wrapper:

   npx @nikolas.sapa/ns-ui add <component-name>
   

   Additional commands (search, list, info, categories) let you explore the catalog from the terminal.
3. MCP server – For agents or automated workflows, start the MCP server:

   npx -y @nikolas.sapa/ns-ui-mcp
   

   The server exposes endpoints such as search_components, get_component, list_categories, install_command, and get_conventions.
4. Static fetch – Retrieve the whole catalog as plain text via:

   GET https://design.helpmarq.com/llms.txt
   

   Use llms-full.txt for detailed behavioral descriptions.

Key features of Ns Ui

• Zero‑runtime package – Components are installed as raw source, giving full editability.
• Tailwind v4 token theming – Light and dark modes are baked in, following a shared token contract.
• Playwright gate – Automated visual and accessibility checks guarantee interactive correctness.
• Two curated collections – core for restrained production UI, loud for experimental showcases.
• Shadcn compatibility – Install via standard npx shadcn add workflow.
• MCP server – Machine‑readable API for search, retrieval, and install command generation.
• CLI tool – Quick terminal access to search, list, and install components.
• Live preview – Browse all components at https://design.helpmarq.com.

Use cases of Ns Ui

• Rapid UI prototyping – Pull individual components directly into a Next.js or React project without managing a separate library version.
• Design‑system enforcement – Ensure every component follows the same Tailwind token set and accessibility standards.
• Agent‑driven development – LLM agents can query the MCP server to pick the right component and install it in two steps.
• Themed applications – Switch between light/dark themes automatically, leveraging the built‑in token contract.
• Educational demos – Showcase advanced interactions (e.g., particle‑hero, caustic‑coverflow) with minimal setup.

FAQ from Ns Ui

Q: Do I need to add a dependency on ns-ui? A: No. Components are added as plain .tsx files, so there is no runtime package to keep in sync.

Q: Which React version is required? A: Any version compatible with Next.js 13+ and Node 22.18 or newer.

Q: How are accessibility issues handled? A: The verification script fails components that lack accessible names, proper ARIA states, or keyboard navigation, ensuring only compliant components are published.

Q: Can I customize the installed component code? A: Absolutely. Since the source is copied into your repo, you can edit props, styles, or logic as needed.

Q: What is the purpose of the MCP server? A: It provides a programmatic interface for agents or tooling to search the catalog, retrieve full component source, and get install commands without manual HTTP fetches.

Q: How do I contribute a new component? A: Add a folder with component.tsx, demo.tsx, and meta.json; registration is automatic via the repository scripts. See CONTRIBUTING.md for details.

ns-ui

218 React components you install by URL, no package to depend on. Every one is built around a single interaction and gated by a Playwright suite that refuses to pass a component whose hover looks identical to its resting state.

Two collections. core (183) is restrained and production-facing, Geist-dark. loud (35) is a deliberately flashy showcase.

Browse them live at design.helpmarq.com.

particle-hero — a field that answers the cursor	pressure-front — contour lines that bunch toward the CTA
caustic-coverflow — drag to scrub, flick for momentum	ridge-walk — pick a point on a pareto frontier
crack-compare — the before/after divider is a fracture	knockout-404 — type carved out of the surface

Install

Any shadcn-configured project, zero config:

npx shadcn add https://design.helpmarq.com/r/<name>.json

That drops the source at components/ui/<name>.tsx and installs the component's npm dependencies. There is no ns-ui package and nothing to keep in sync. The code is yours to edit.

New project:

npx shadcn init -d
npx shadcn add https://design.helpmarq.com/r/caustic-coverflow.json

For agents

GET https://design.helpmarq.com/llms.txt

One fetch returns the whole catalog as plain text: every component, its props, the situation it suits, and its exact install command. No tool definitions, no pagination. An agent that can make an HTTP request can pick the right component and install it in two steps.

llms-full.txt at the same origin adds the full behavioral description per component, hand-written rather than derived from tags, for the cases where several components share a UI role and a model has to tell them apart.

/registry.json serves the standard shadcn registry index for tools that expect it.

Prefer tools over a one-time fetch (an agent working across a whole session, not just picking one component up front)? mcp/ is an MCP server over the same catalog — search_components, get_component (full prop signature + real source), list_categories, install_command, and get_conventions (the token/theming contract). npx -y @nikolas.sapa/ns-ui-mcp, stdio transport, per-client config at design.helpmarq.com/connect or mcp/README.md.

There's also a thin CLI, cli/ (@nikolas.sapa/ns-ui): npx @nikolas.sapa/ns-ui add <name> installs a component, search/list/info/ categories cover the rest of the catalog from a terminal. See cli/README.md.

The gate

scripts/verify.ts is why the registry stays small. It drives every component through headless Chromium, screenshots each state against each theme, and hard-fails on:

• a console error, or a blank render
• hover byte-identical to default, or focus identical to an unfocused baseline (an interaction that does not actually interact)
• dark and light byte-identical (a component that ignored the theme)
• an interactive control with no accessible name, role=switch|checkbox|radio without aria-checked, a visible dialog with no accessible name, or controls Tab cannot reach
• a popover or menu that opens but lands clipped invisible behind an ancestor's overflow: hidden, caught by hit-testing the opened element rather than measuring its box

The screenshots it produces are committed, so the claims above are auditable in the repo rather than asserted here.

Run it locally

npm install
npm run dev            # / lists components, /preview/<name> renders one
npm run verify         # the gate, in another shell, with dev running

Node 22.18 or newer.

Environment variables

Copy .env.example to .env and fill in what you need. Everything is optional locally — the app still runs and the email form still renders, it just returns an error on submit if the EmailOctopus vars are unset.

Variable	Purpose
NEXT_PUBLIC_REGISTRY_ORIGIN	Overrides the public origin install commands and llms.txt resolve against. Defaults to https://design.helpmarq.com.
EMAILOCTOPUS_API_KEY	Bearer key for the EmailOctopus v2 API, used by the email capture form (lib/actions/subscribe.ts). Server-only, never exposed to the client.
EMAILOCTOPUS_LIST_ID	The EmailOctopus list contacts are added to.

Adding a component means creating a folder with component.tsx, demo.tsx and meta.json; registration is automatic. See CONTRIBUTING.md, and AGENTS.md if you are an agent working inside this repo.

License

MIT. See LICENSE.