Telepat Design System

A React + TypeScript component library implementing the Telepat brand — dark-first, paired-glow atmospheric design — with full Storybook documentation.

---

Visual identity

Logomark the spiral glyph

Hero backdrop topographic lines + paired glow

Vision motif magnetic field + eclipse silhouette

The three service pillars

AI Software Development	AI Visuals & Voice	Security & Infrastructure

Surface pairs

#000000 bg	#14102B bg-deep	#221949 bg-elevated	#FFFFFF bg-light	#F6F6F6 bg-light-soft

Telepat is dark-first — roughly 80% of the deck and the entire site live on #000 or #14102B. White appears only as the right pane of split-screen deck slides; #F6F6F6 is reserved for use-case photo tiles. There are no mid-gray surfaces — the system is binary.

---

Quick start

The package is published to the GitHub Packages npm registry under the @telepat-io scope. GitHub Packages requires authentication for all installs — including from public repositories — so consumers need a Personal Access Token before npm install will work.

1. Create a Personal Access Token

Generate a token at https://github.com/settings/tokens/new with the read:packages scope. Classic PATs work; fine-grained PATs also work if the token grants "Packages: read" on the telepat-io organization.

2. Configure your project's .npmrc

Add to .npmrc at the root of your project (or ~/.npmrc for global access):

@telepat-io:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Export GITHUB_TOKEN in your shell (export GITHUB_TOKEN=ghp_...) or hard-code the token directly in .npmrc if you understand the trade-off.

3. Install and use

npm install @telepat-io/telepat-design-system

import "@telepat-io/telepat-design-system/styles.css";
import { Button, TextInput, Nav, TestimonialCard } from "@telepat-io/telepat-design-system";
import { Hero, ContactSection } from "@telepat-io/telepat-design-system/sections";

export function App() {
  return (
    <>
      <Hero />
      <ContactSection onSubmit={(values) => console.log(values)} />
    </>
  );
}

Fonts

The library bundles a Montserrat Alternates family (renamed to "Montserrat Alt1" internally so consumers don't have to swap a CSS variable) for the TELEPAT wordmark. It's licensed under SIL OFL 1.1 and bundled in dist/fonts/ along with its OFL.txt.

Poppins must be loaded by the host application — typically via Google Fonts:

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Poppins:ital,wght@0,300;0,400;0,500;0,600;0,700;1,300&display=swap">

---

What's in the library

Atoms

Button · TextInput · Textarea · Select · DateInput · Checkbox · Radio · SegmentedControl · Toggle · Slider · Chip / Chips · Dropzone · Logo · LinkMore · Eyebrow · NavLink · GlowBackground

Molecules

Nav · Footer · TestimonialCard · TestimonialCarousel · ServiceRow · ServiceCard · ClientGrid

Sections

Hero · ServicesSection · CustomersSection · VisionSection · ContactSection

Sections are published under a separate entry point (telepat-design-system/sections) so apps that only need atoms don't pull in the bundled section imagery.

// Atoms / molecules only — tiny bundle (~12 kB ESM + tokens)
import { Button } from "@telepat-io/telepat-design-system";

// Adds page-level sections + their imagery
import { Hero } from "@telepat-io/telepat-design-system/sections";

---

Brand principles

• Dark-first. Surfaces default to #000 or #14102B deep purple-black.
• Paired radial glow. Every dark surface carries a translucent blue disk top-right and a magenta disk bottom-left. Composable via <GlowBackground />.
• No emoji, no exclamation marks, no shadows. Atmospheric depth comes from glow + mix-blend-mode: lighten.
• Type. Poppins Light (300) is the default weight; italic is reserved for vision/quote moments. The wordmark uses Montserrat Alt1 Medium with +0.080em tracking.

See src/styles/tokens.css for the full token set.

---

Development

npm install
npm run fetch-fonts      # download Montserrat Alternates (OFL 1.1) into src/fonts/
npm run dev              # Storybook at http://localhost:6006
npm run build            # build the library to dist/
npm run build-storybook  # static Storybook to storybook-static/
npm run typecheck

fetch-fonts is idempotent and auto-runs before dev / build / build-storybook via npm pre* hooks, so the explicit invocation above is only needed once after a fresh clone — or never, if you're fine with the auto-run.

Storybook is the source of truth for browsing every component, every state, and every foundation specimen (Colors / Typography / Spacing / Brand).

---

Project files

• src/components/atoms/ — primitives (each: .tsx + .module.css + .stories.tsx + index.ts)
• src/components/molecules/ — composed pieces
• src/components/sections/ — page-level templates
• src/stories/Foundations/ — design-token specimens
• src/styles/tokens.css — full token set (colors, type, spacing, radii, glow)
• src/styles/fonts.css — @font-face for Montserrat Alt1
• src/assets/ — logos, hero PNG, service imagery, magnetic-field PNG, use-case photos
• vite.config.ts — library build (ESM + CJS + d.ts, two entry points)

For contributor / agent guidance, see AGENTS.md.

---

Contributing — releases and commit messages

This repo uses release-please to automate versioning, changelog generation, and publishing to GitHub Packages. Versioning is driven entirely by commit messages, so commits to main must follow the Conventional Commits format.

Commit prefix	Version bump	Use for
fix:	patch (1.0.0 → 1.0.1)	bug fixes
feat:	minor (1.0.0 → 1.1.0)	new components, new exports, additive features
feat!: or BREAKING CHANGE: footer	major (1.0.0 → 2.0.0)	breaking API or visual changes
chore: / docs: / refactor: / ci: / style: / test:	no release	maintenance work

How a release happens

1. You merge a PR into main with a Conventional Commit message.
2. The release workflow opens (or updates) a single Release PR titled chore(main): release <version> that bumps package.json + writes the CHANGELOG.
3. When you're ready to ship, merge the Release PR. The publish workflow then tags the commit v<version>, creates a GitHub Release, and pushes the package to GitHub Packages.

Forcing a specific version

To force the next release to a specific version (e.g., a deliberate major bump regardless of commit types), add a footer to any commit:

chore: prepare 2.0.0

Release-As: 2.0.0

You can also edit .release-please-manifest.json directly in a PR — release-please respects whatever version is there.

---

License & attribution

• Source code, configuration, stories, and CSS Modules in this repository are licensed under the MIT License.
• Fonts. This repo fetches Montserrat Alternates (Copyright 2011 The Montserrat Project Authors, https://github.com/JulietaUla/Montserrat) from the official Google Fonts repository on demand via npm run fetch-fonts. The font is distributed under the SIL Open Font License 1.1 and OFL.txt ships alongside it in dist/fonts/ so consumers receive attribution automatically. The original Telepat design specifies the commercial "Montserrat Alt1" variant; Alternates is the closest freely-redistributable family member. If you have an Alt1 license, drop the files into src/fonts/ named MontserratAlt1-<Weight>.ttf and the fetch script will preserve them.
• Brand assets (logos, hero/vision imagery, service photography, use-case photo pairs) in src/assets/ are property of Telepat (telepat.io). They're included as design references — replace before any production use.

Caveats

• Hover and press states are extrapolated defaults (not in the source Figma). Adjust to taste.