tessl/npm-storybook-design-token

Storybook addon to display design token documentation generated from your stylesheets and icon files.

—

Pending

Overview

Eval results

Files

Token Presenters

Name: tessl/npm-storybook-design-token
Author: tessl

Visual presentation components for different types of design tokens including colors, typography, spacing, animations, and more. The system includes 15 built-in presenters and supports custom presenter extensions for specialized token types.

Capabilities

TokenPreview Component

Main component for rendering individual design tokens with appropriate visual presentation based on the token type.

/**
 * Renders a design token with appropriate visual presentation
 * @param props - Token and presenter configuration
 * @returns JSX element with token visualization
 */
function TokenPreview(props: TokenPreviewProps): JSX.Element;

interface TokenPreviewProps {
  /** Token data to display */
  token: Token;
  /** Custom presenter components to override defaults */
  presenters?: PresenterMapType;
}

Usage Examples:

import { TokenPreview, Token, TokenPresenter } from "storybook-design-token";

const colorToken: Token = {
  name: "primary-blue",
  value: "#0066cc",
  rawValue: "$primary-blue",
  presenter: TokenPresenter.COLOR,
  sourceType: TokenSourceType.SCSS,
  sourcePath: "./tokens/colors.scss"
};

// Basic token preview
<TokenPreview token={colorToken} />

// With custom presenter override
<TokenPreview 
  token={colorToken}
  presenters={{ "Color": MyCustomColorPresenter }}
/>

Built-in Presenter Components

Color and Visual Presenters

Visual presentation for color values, opacity, and gradients.

/** Displays color swatches with hex/rgb values */
function ColorPresenter(props: PresenterProps): JSX.Element;

/** Shows opacity values with visual transparency examples */
function OpacityPresenter(props: PresenterProps): JSX.Element;

Typography Presenters

Font-related token presentations showing actual typeface examples and measurements.

/** Displays font family names with sample text */
function FontFamilyPresenter(props: PresenterProps): JSX.Element;

/** Shows font sizes with scaled text examples */
function FontSizePresenter(props: PresenterProps): JSX.Element;

/** Demonstrates font weights with visual examples */
function FontWeightPresenter(props: PresenterProps): JSX.Element;

/** Visualizes line height with text examples */
function LineHeightPresenter(props: PresenterProps): JSX.Element;

/** Shows letter spacing with text examples */
function LetterSpacingPresenter(props: PresenterProps): JSX.Element;

Layout and Spacing Presenters

Visual representations for spacing, borders, shadows, and layout properties.

/** Displays spacing values with visual boxes */
function SpacingPresenter(props: PresenterProps): JSX.Element;

/** Shows border styles and properties */
function BorderPresenter(props: PresenterProps): JSX.Element;

/** Visualizes border radius with rounded shapes */
function BorderRadiusPresenter(props: PresenterProps): JSX.Element;

/** Displays shadow effects with examples */
function ShadowPresenter(props: PresenterProps): JSX.Element;

Animation and Motion Presenters

Presentation for animation-related tokens including timing and easing functions.

/** Shows animation properties with live previews */
function AnimationPresenter(props: PresenterProps): JSX.Element;

/** Visualizes easing functions with curve examples */
function EasingPresenter(props: PresenterProps): JSX.Element;

Asset Presenters

Presentation for media assets including images and SVG icons.

/** Renders SVG icons with metadata */
function SvgPresenter(props: PresenterProps): JSX.Element;

/** Displays image assets with dimensions */
function ImagePresenter(props: PresenterProps): JSX.Element;

/** Fallback presenter for undefined or empty tokens */
function EmptyPresenter(props: PresenterProps): JSX.Element;

Custom Presenter Development

Create custom presenter components for specialized token types or unique presentation requirements.

interface PresenterProps {
  /** Token data containing all relevant information */
  token: Token;
}

interface PresenterMapType {
  /** Map of presenter names to React components */
  [key: string]: React.FunctionComponent<PresenterProps> | React.ComponentClass<PresenterProps>;
}

Usage Examples:

import React from "react";
import { PresenterProps } from "storybook-design-token";

// Custom gradient presenter
const GradientPresenter: React.FC<PresenterProps> = ({ token }) => {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
      <div
        style={{
          width: "200px",
          height: "40px",
          background: token.value,
          borderRadius: "4px",
          border: "1px solid #ddd"
        }}
      />
      <div>
        <strong>{token.name}</strong>
        <br />
        <code style={{ fontSize: "12px", color: "#666" }}>
          {token.value}
        </code>
        {token.description && (
          <p style={{ fontSize: "12px", margin: "4px 0 0" }}>
            {token.description}
          </p>
        )}
      </div>
    </div>
  );
};

// Custom dimension presenter for width/height tokens
const DimensionPresenter: React.FC<PresenterProps> = ({ token }) => {
  const pixelValue = parseInt(token.value.replace(/[^\d]/g, ""));
  
  return (
    <div style={{ display: "flex", alignItems: "center", gap: "12px" }}>
      <div
        style={{
          width: pixelValue > 100 ? "100px" : `${pixelValue}px`,
          height: "20px",
          backgroundColor: "#e3f2fd",
          border: "2px solid #2196f3",
          position: "relative"
        }}
      >
        <span style={{
          position: "absolute",
          top: "-20px",
          left: "0",
          fontSize: "10px",
          color: "#666"
        }}>
          {token.value}
        </span>
      </div>
      <div>
        <strong>{token.name}</strong>
        <br />
        <span style={{ fontSize: "12px", color: "#666" }}>
          {token.description || "Dimension value"}
        </span>
      </div>
    </div>
  );
};

// Register custom presenters
const customPresenters = {
  "Gradient": GradientPresenter,
  "Dimension": DimensionPresenter
};

// Use in TokenPreview or DesignTokenDocBlock
<TokenPreview 
  token={myToken} 
  presenters={customPresenters}
/>

Presenter System Architecture

The presenter system automatically selects the appropriate presenter based on the token's presenter property, falling back to the EmptyPresenter for undefined types.

/** Built-in presenter mapping */
const PresenterMap: PresenterMapType = {
  [`${TokenPresenter.ANIMATION}`]: AnimationPresenter,
  [`${TokenPresenter.BORDER}`]: BorderPresenter,
  [`${TokenPresenter.BORDER_RADIUS}`]: BorderRadiusPresenter,
  [`${TokenPresenter.COLOR}`]: ColorPresenter,
  [`${TokenPresenter.EASING}`]: EasingPresenter,
  [`${TokenPresenter.FONT_FAMILY}`]: FontFamilyPresenter,
  [`${TokenPresenter.FONT_SIZE}`]: FontSizePresenter,
  [`${TokenPresenter.FONT_WEIGHT}`]: FontWeightPresenter,
  [`${TokenPresenter.LINE_HEIGHT}`]: LineHeightPresenter,
  [`${TokenPresenter.LETTER_SPACING}`]: LetterSpacingPresenter,
  [`${TokenPresenter.OPACITY}`]: OpacityPresenter,
  [`${TokenPresenter.SHADOW}`]: ShadowPresenter,
  [`${TokenPresenter.SPACING}`]: SpacingPresenter,
  [`${TokenPresenter.SVG}`]: SvgPresenter,
  [`${TokenPresenter.IMAGE}`]: ImagePresenter
};

Selection Logic:

Check if token has a presenter property
Look up presenter in combined map (custom presenters override built-in ones)
Fall back to EmptyPresenter if no match found
Render the selected presenter component with token data

Install with Tessl CLI

npx tessl i tessl/npm-storybook-design-token

docs