@telnyx/ui-kit

Telnyx component registry built on shadcn/ui. Five domain-specific components with Telnyx brand tokens, available as an npm package (@telnyx/ui) or installable via the telnyx-ui CLI.

This is a foundation, not a finished library. We ship 5 Telnyx domain components and 4 UI primitives today. To be broadly useful across Portal, Mission Control, and internal tools, this needs significantly more components and complete theme population. See What's Needed below.

What's Needed

More Components

We currently have 5 domain components and 4 basic UI primitives. A production-ready internal library needs considerably more. Priority additions:

Domain components (Telnyx-specific, high value):

• SipCredentialDisplay — SIP username/password with masked display
• CallFlowDiagram — Visual SIP call flow / WebRTC session rendering
• UsageChart — Branded charts for billing/usage dashboards
• NumberSearchResult — Phone number display with features/capabilities
• ConnectionCard — SIP connection or FQDN status overview
• BillingTable — Invoices, CDRs, usage records with Telnyx formatting
• WebhookPayload — Structured webhook event viewer

UI primitives (extend shadcn/ui coverage):

• Dialog, Sheet, Select, Tabs, Table, Card, DropdownMenu, Command palette, Form, Alert, Toast, Accordion, Popover, Switch, Checkbox, Radio, Skeleton, Avatar, Separator, ScrollArea

These lists are starting points. Teams should open issues for components they need.

Theme Population

Two theme files exist but need real token values filled in:

| File | Status | Needed | |------|--------|--------| | themes/telnyx-tokens.css | Complete — canonical brand tokens | Maintained by design | | themes/portal.css | Placeholder — needs real Portal values | Full Portal color scheme, spacing, radius, typography overrides | | themes/dotcom.css | Placeholder — needs real dotcom/marketing values | Full marketing site color scheme, spacing, radius, typography overrides |

Portal and dotcom designs are quite different. Until both CSS files have real production values, theme switching is structural but not functional. This is a design team deliverable (Zara's pass).

How to Contribute

Pick a component, check CONTRIBUTING.md for the authoring guide, and open a PR. Every new component should include a Storybook story and tests.

Install the CLI

One-time setup (requires gh CLI authenticated to team-telnyx):

curl -sfH "Authorization: token $(gh auth token)" \
  -H "Accept: application/vnd.github.raw+json" \
  "https://api.github.com/repos/team-telnyx/telnyx-ui-kit/contents/bin/telnyx-ui" \
  -o /usr/local/bin/telnyx-ui && chmod +x /usr/local/bin/telnyx-ui

Components (Current)

We have 5 domain components today. This is the starting set, not the finish line.

| Component | Description | |-----------|-------------| | api-key-display | Masked API key with copy button | | status-badge | Status indicator for calls, connections, resources | | phone-number | E.164 display with country flags + input with formatting | | json-viewer | Collapsible JSON tree with syntax highlighting | | code-block | Syntax highlighting via shiki with copy and line numbers |

UI primitives (button, badge, tooltip, input) are included for dependency resolution. They are not intended to replace primitives teams already use.

Quick Start

# List everything available
telnyx-ui list

# Install one component
telnyx-ui add status-badge

# Install several at once
telnyx-ui add api-key-display phone-number json-viewer code-block

# Install the Telnyx theme (optional)
telnyx-ui add telnyx-theme

Then use it:

import { ApiKeyDisplay } from "@/components/api-key-display"
import { StatusBadge } from "@/components/status-badge"
import { PhoneNumber } from "@/components/phone-number"
import { JsonViewer } from "@/components/json-viewer"
import { CodeBlock } from "@/components/code-block"

<ApiKeyDisplay value="KEY0123456789abcdef" />
<StatusBadge status="active" category="resource" />
<PhoneNumber value="+14155551234" />
<JsonViewer data={{ id: "conn_abc", status: "active" }} />
<CodeBlock language="bash">{'curl https://api.telnyx.com/v2/calls'}</CodeBlock>

Prerequisites

• React 18 or 19
• Tailwind CSS 4+
• TypeScript 5+
• shadcn/ui initialized (npx shadcn init)
• components.json with aliases configured:

{
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "aliases": {
    "components": "src/components",
    "ui": "src/components/ui",
    "lib": "src/lib",
    "utils": "src/lib/utils"
  }
}

Component Dependencies

Each component includes its UI primitive dependencies (button, badge, tooltip, input) automatically.

| Component | UI Primitives | NPM Packages | |-----------|--------------|--------------| | api-key-display | button, tooltip | - | | status-badge | badge | - | | phone-number | button, tooltip, input | libphonenumber-js | | json-viewer | button, tooltip | - | | code-block | button, tooltip | shiki |

Development

git clone https://github.com/team-telnyx/telnyx-ui-kit.git
cd telnyx-ui-kit
pnpm install
pnpm storybook        # Dev server on :6006
pnpm registry:build   # Rebuild registry JSON
pnpm build-storybook  # Static Storybook build

Brand Tokens

| Token | Value | |-------|-------| | Primary | #00e3aa | | Blue | #3434ef | | Red | #eb0000 | | Cream | #fefdf5 | | Headings | ppFormulaFont | | Body | Inter |

Full token definitions in themes/telnyx-tokens.css.

Contributing

See CONTRIBUTING.md for component authoring guide and PR process.

License

ISC