tessl/npm-keystone-ui--core

Core design system components and utilities for KeystoneJS applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Theme System

Name: tessl/npm-keystone-ui--core
Author: tessl

Complete theming system with React Context, comprehensive design tokens, responsive utilities, and TypeScript support. The theme system provides consistent design values across all components and enables responsive design patterns.

Capabilities

Theme Provider and Context

React Context-based theme system for providing theme values throughout the component tree.

/**
 * Theme context provider component
 * @param props - Provider props with theme and children
 * @returns JSX element providing theme context
 */
function ThemeProvider(props: ThemeProviderProps): JSX.Element;

interface ThemeProviderProps {
  /** Theme object containing all design tokens */
  theme: Theme;
  /** Child components that will have access to theme */
  children: ReactNode;
}

/**
 * React context for theme values
 */
const ThemeContext: React.Context<{ theme: Theme }>;

/**
 * Hook to access the current theme from context
 * @returns Current theme object with all design tokens
 */
function useTheme(): Theme;

Usage Examples:

import { ThemeProvider, useTheme } from "@keystone-ui/core";
// Import default theme separately - check your build configuration for exact path
// import { theme } from "@keystone-ui/core/themes/default";

// Use the default theme or create custom theme
const defaultTheme = { /* default theme object */ };

// Provide theme to application
function App() {
  return (
    <ThemeProvider theme={defaultTheme}>
      <MyComponent />
    </ThemeProvider>
  );
}

// Access theme in components
function MyComponent() {
  const { colors, spacing, typography } = useTheme();
  
  return (
    <div style={{ 
      color: colors.foreground,
      padding: spacing.medium,
      fontFamily: typography.fontFamily.body
    }}>
      Themed content
    </div>
  );
}

// Custom theme
const customTheme = {
  ...theme,
  colors: {
    ...theme.colors,
    background: '#f5f5f5'
  }
};

<ThemeProvider theme={customTheme}>
  <App />
</ThemeProvider>

Default Theme

Complete default theme object containing all design tokens and system values.

/**
 * Default theme object with complete design system tokens
 */
const theme: Theme;

/**
 * Theme type derived from the default theme object
 */
type Theme = typeof theme;

Accessing the Default Theme:

The default theme object is not directly exported from the main package entry point. To use the default theme, you'll need to import it from its specific location:

// Import from themes/default - actual path may vary based on build configuration
import { theme } from "@keystone-ui/core/themes/default";

// Or create your own theme following the Theme type structure
const customTheme: Theme = {
  // ... your theme configuration
};

Responsive Media Query Utilities

Hook providing responsive design utilities built on Facepaint for breakpoint-based styling.

/**
 * Hook providing responsive design utilities
 * @returns Object with media query utilities
 */
function useMediaQuery(): MediaQueryUtilities;

interface MediaQueryUtilities {
  /** Facepaint media query function for array-based responsive styles */
  mq: (styles: ResponsiveStyles) => any;
  /** Generate min-width media query string */  
  minBreak: (key: keyof Theme['breakpoints']) => string;
  /** Generate max-width media query string */
  maxBreak: (key: keyof Theme['breakpoints']) => string;
}

type ResponsiveStyles = {
  [property: string]: any | any[];
};

Usage Examples:

import { useMediaQuery, css } from "@keystone-ui/core";

function ResponsiveComponent() {
  const { mq, minBreak, maxBreak } = useMediaQuery();
  
  // Array-based responsive styles
  const responsiveStyles = mq({
    fontSize: ['14px', '16px', '18px', '20px'],
    padding: ['8px', '12px', '16px', '24px'],
    color: ['blue', 'green']
  });
  
  // Manual media queries
  const manualStyles = css`
    font-size: 14px;
    
    ${minBreak('medium')} {
      font-size: 18px;
    }
    
    ${maxBreak('small')} {
      display: none;
    }
  `;
  
  return <div css={responsiveStyles}>Responsive content</div>;
}

Theme Structure

Typography Scale

Complete typography system with font families, sizes, weights, and spacing.

interface Typography {
  fontFamily: {
    body: string;
    heading: string;
    monospace: string;
  };
  fontSize: {
    xxxsmall: string;
    xxsmall: string;
    xsmall: string;
    small: string;
    medium: string;
    large: string;
    xlarge: string;
    xxlarge: string;
    xxxlarge: string;
    xxxxlarge: string;
    xxxxxlarge: string;
    xxxxxxlarge: string;
  };
  fontWeight: {
    light: number;
    regular: number;
    medium: number;
    semibold: number;
    bold: number;
    heavy: number;
  };
  leading: {
    tighter: number;
    tight: number;
    base: number;
    loose: number;
    looser: number;
  };
  tracking: {
    tighter: string;
    tight: string;
    base: string;
    loose: string;
    looser: string;
  };
}

Color Palette

Comprehensive color system with neutral colors and semantic color scales.

interface Palette {
  // Base colors
  black: string;
  white: string;
  current: string;
  transparent: string;
  
  // Neutral scale
  neutral100: string;
  neutral200: string;
  neutral300: string;
  neutral400: string;
  neutral500: string;
  neutral600: string;
  neutral700: string;
  neutral800: string;
  neutral900: string;
  
  // Semantic color scales (50-900)
  blue50: string;
  blue100: string;
  // ... through blue900
  
  green50: string;
  green100: string;
  // ... through green900
  
  red50: string;
  red100: string;
  // ... through red900
  
  yellow50: string;
  yellow100: string;
  // ... through yellow900
  
  purple50: string;
  purple100: string;
  // ... through purple900
  
  pink50: string;
  pink100: string;
  // ... through pink900
}

interface Colors {
  background: string;
  backgroundMuted: string;
  backgroundDim: string;
  backgroundHover: string;
  border: string;
  borderCritical: string;
  borderFocus: string;
  focusRing: string;
  foreground: string;
  foregroundMuted: string;
  foregroundDim: string;
  foregroundDisabled: string;
  linkColor: string;
  linkHoverColor: string;
  overlayBackground: string;
  loaderDark: string;
  loaderLight: string;
}

Spacing and Layout

Spacing scales, breakpoints, sizing, and border radius values.

interface Spacing {
  none: number;
  xxsmall: number;
  xsmall: number;
  small: number;
  medium: number;
  large: number;
  xlarge: number;
  xxlarge: number;
}

interface Breakpoints {
  small: number;   // 576px
  medium: number;  // 768px
  large: number;   // 992px
  xlarge: number;  // 1200px
}

interface Sizing {
  xxsmall: number; // 16px
  xsmall: number;  // 20px
  small: number;   // 24px
  medium: number;  // 32px
  large: number;   // 38px
  xlarge: number;  // 42px
  xxlarge: number; // 48px
}

interface Radii {
  none: number;    // 0
  xsmall: number;  // 4px
  small: number;   // 6px
  medium: number;  // 8px
  large: number;   // 12px
  full: number;    // 9999px
}

Visual Effects

Shadows, elevation, opacity, and animation values.

interface Shadow {
  s100: string; // Cards
  s200: string; // Inline dialogs
  s300: string; // Tooltip
  s400: string; // Modals
  s500: string; // Toasts
}

interface Elevation {
  e100: number; // 100 - Cards
  e200: number; // 200 - Inline dialogs
  e300: number; // 300 - Tooltip
  e400: number; // 400 - Modals
  e500: number; // 500 - Toasts
}

interface Opacity {
  full: number;     // 1
  none: number;     // 0
  disabled: number; // 0.65
}

interface Animation {
  duration0: string;    // 0ms
  duration50: string;   // 40ms
  duration100: string;  // 130ms
  // ... through duration1000
  
  spring: string;       // cubic-bezier(0.2, 0, 0, 1.6)
  easeInOut: string;    // cubic-bezier(.45, 0, .40, 1)
  easeIn: string;       // cubic-bezier(0.2, 0, 0, 1)
  easeOut: string;      // cubic-bezier(0.165, 0.840, 0.440, 1)
  linear: string;       // cubic-bezier(0, 0, 1, 1)
}

Component-Specific Tokens

Specialized tokens for headings, controls, and form fields.

interface HeadingStyles {
  h1: HeadingStyle;
  h2: HeadingStyle;
  h3: HeadingStyle;
  h4: HeadingStyle;
  h5: HeadingStyle;
  h6: HeadingStyle;
}

interface HeadingStyle {
  color: string;
  family: string;
  size: string;
  transform: string;
  weight: number;
}

interface ControlSizes {
  small: ControlSize;
  medium: ControlSize;
  large: ControlSize;
}

interface ControlSize {
  borderRadius: number;
  borderWidth: number;
  gutter: number;
  paddingX: number;
  paddingY: number;
  height: number;
  gap: number;
  fontSize: number | string;
  indicatorBoxSize: number | string;
  indicatorFontSize: number | string;
}

Contextual Color Tones

Semantic color schemes for different UI states and contexts.

interface Tones {
  active: Tone;
  passive: Tone;
  positive: Tone;
  warning: Tone;
  negative: Tone;
  help: Tone;
}

interface Tone {
  focusRing: string;
  border: [string, string, string];      // [default, hover, active]
  fill: [string, string, string];        // [default, hover, active]
  tint: [string, string, string];        // [subtle, medium, stronger]
  foreground: [string, string, string];  // [default, hover, active]
  fillForeground: [string, string, string]; // Text on fill backgrounds
}

interface SelectableColors {
  silver: SelectableColor;
  grey: SelectableColor;
  blue: SelectableColor;
  pink: SelectableColor;
  green: SelectableColor;
  purple: SelectableColor;
}

interface SelectableColor {
  border: string;
  fill: string;
  fillForeground: string;
  foreground: string;
  tint: string;
}

Form Field Styling Tokens

Comprehensive styling tokens for form inputs, controls, and interactive states.

interface Fields {
  // Base control styling
  controlBackground?: string;
  controlBorderColor?: string;
  controlBorderRadius?: number | string;
  controlBorderWidth?: number | string;
  controlForeground?: string;
  
  // Input field styling
  inputBackground?: string;
  inputBorderColor?: string;
  inputBorderRadius?: number | string;
  inputBorderWidth?: number | string;
  inputForeground?: string;
  inputPlaceholder?: string;
  
  // Labels and legends
  labelColor?: string;
  legendColor?: string;
  
  // Special controls
  switchForeground?: string;
  
  // Interactive states
  disabled: FieldStateTokens;
  focus: FieldStateTokens;
  hover: FieldStateTokens;
  invalid: FieldStateTokens;
  selected: FieldStateTokens;
}

interface FieldStateTokens {
  // Shared properties
  labelColor?: string;
  legendColor?: string;
  shadow?: string;
  
  // Control-specific properties
  controlBackground?: string;
  controlBorderColor?: string;
  controlBorderRadius?: number | string;
  controlForeground?: string;
  
  // Input-specific properties
  inputBackground?: string;
  inputBorderColor?: string;
  inputBorderRadius?: number | string;
  inputForeground?: string;
  iconColor?: string;
}

Custom Theming

Create custom themes by extending or overriding the default theme:

import { theme as defaultTheme } from "@keystone-ui/core";

// Extend existing theme
const customTheme = {
  ...defaultTheme,
  colors: {
    ...defaultTheme.colors,
    background: '#fafafa',
    foreground: '#333333'
  },
  spacing: {
    ...defaultTheme.spacing,
    huge: 64 // Add custom spacing value
  }
};

// Use custom theme
<ThemeProvider theme={customTheme}>
  <App />
</ThemeProvider>

TypeScript Integration

The theme system provides full TypeScript support with type-safe access to all theme values:

import { Theme } from "@keystone-ui/core";

// Type-safe theme usage
function useCustomStyles() {
  const theme = useTheme();
  
  // All theme properties are typed
  const styles = {
    color: theme.colors.foreground,        // ✓ Type-safe
    fontSize: theme.typography.fontSize.large, // ✓ Type-safe  
    padding: theme.spacing.medium,         // ✓ Type-safe
    // backgroundColor: theme.colors.invalid  // ✗ TypeScript error
  };
  
  return styles;
}

// Responsive prop type helper
type ResponsiveProp<T> = T | readonly (T | null)[];

// Usage in custom components
interface MyComponentProps {
  color?: ResponsiveProp<keyof Theme['palette']>;
  spacing?: ResponsiveProp<keyof Theme['spacing']>;
}