brandspec 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,402 @@
+/** Brand metadata. Only `name` is required. */
+interface BrandspecMeta {
+    name: string;
+    version?: string;
+    updated?: string;
+    description?: string;
+    url?: string;
+    [key: string]: unknown;
+}
+interface BrandspecVoice {
+    tone?: string[];
+    principles?: string[];
+    [key: string]: unknown;
+}
+interface BrandspecCore {
+    essence?: string;
+    tagline?: string;
+    mission?: string;
+    vision?: string;
+    values?: string[];
+    personality?: string[];
+    voice?: BrandspecVoice;
+    [key: string]: unknown;
+}
+/** W3C DTCG-compliant design token. */
+interface DesignToken {
+    $value: string;
+    $type?: string;
+    $description?: string;
+    $extensions?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface BrandspecTokens {
+    colors?: Record<string, DesignToken>;
+    typography?: Record<string, DesignToken>;
+    spacing?: Record<string, DesignToken>;
+    radius?: Record<string, DesignToken>;
+    [key: string]: Record<string, DesignToken> | undefined;
+}
+interface BrandspecAsset {
+    file: string;
+    id?: string;
+    role?: string;
+    variant?: string;
+    context?: string;
+    description?: string;
+    formats?: Array<{
+        path: string;
+        width?: number;
+        height?: number;
+    }>;
+    tags?: string[];
+    [key: string]: unknown;
+}
+interface GuidelineRule {
+    id?: string;
+    description: string;
+    severity: "info" | "warning" | "error";
+    criteria?: string[];
+    applies_to?: string;
+    [key: string]: unknown;
+}
+interface GuidelineSection {
+    content?: string;
+    rules?: GuidelineRule[];
+    [key: string]: unknown;
+}
+interface BrandspecYaml {
+    meta: BrandspecMeta;
+    core?: BrandspecCore;
+    tokens?: BrandspecTokens;
+    assets?: BrandspecAsset[];
+    guidelines?: Record<string, GuidelineSection>;
+    extensions?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface ParseResult {
+    success: boolean;
+    data?: BrandspecYaml;
+    errors: string[];
+    warnings: string[];
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+
+/**
+ * Parse a YAML string into a typed BrandspecYaml object.
+ * Performs structural validation (required fields, correct types).
+ * For full schema validation, use `validate()` after parsing.
+ */
+declare function parse(content: string): ParseResult;
+/** Serialize a BrandspecYaml object back to YAML string. */
+declare function serialize(data: BrandspecYaml): string;
+
+/**
+ * Validate a parsed object against the brandspec JSON Schema.
+ * Use `parse()` first to get a typed object, then `validate()` for full schema compliance.
+ */
+declare function validate(data: unknown): ValidationResult;
+
+/**
+ * brandspec JSON Schema v0.1.0
+ * Bundled from schema/v0.1.0.yaml
+ *
+ * This is the canonical schema inlined as a JS object
+ * so it ships with the package without runtime YAML parsing.
+ */
+declare const schema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://brandspec.tools/schema/v0.1.0";
+    readonly title: "brandspec";
+    readonly description: "Brand Identity specification format";
+    readonly type: "object";
+    readonly required: readonly ["meta"];
+    readonly properties: {
+        readonly meta: {
+            readonly type: "object";
+            readonly description: "Brand metadata";
+            readonly required: readonly ["name"];
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                    readonly description: "Brand name";
+                };
+                readonly version: {
+                    readonly type: "string";
+                    readonly description: "Brand spec version (semver)";
+                };
+                readonly updated: {
+                    readonly type: "string";
+                    readonly format: "date";
+                    readonly description: "Last updated date";
+                };
+                readonly description: {
+                    readonly type: "string";
+                    readonly description: "Brief brand description";
+                };
+                readonly url: {
+                    readonly type: "string";
+                    readonly format: "uri";
+                    readonly description: "Brand website";
+                };
+            };
+            readonly additionalProperties: true;
+        };
+        readonly core: {
+            readonly type: "object";
+            readonly description: "Brand essence, personality, and voice";
+            readonly properties: {
+                readonly essence: {
+                    readonly type: "string";
+                };
+                readonly tagline: {
+                    readonly type: "string";
+                };
+                readonly mission: {
+                    readonly type: "string";
+                };
+                readonly vision: {
+                    readonly type: "string";
+                };
+                readonly values: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly personality: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly voice: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly tone: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly principles: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                    readonly additionalProperties: true;
+                };
+            };
+            readonly additionalProperties: true;
+        };
+        readonly tokens: {
+            readonly type: "object";
+            readonly description: "Design tokens (W3C DTCG compliant)";
+            readonly additionalProperties: true;
+        };
+        readonly assets: {
+            readonly type: "array";
+            readonly description: "Brand assets";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["file"];
+                readonly properties: {
+                    readonly file: {
+                        readonly type: "string";
+                    };
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly role: {
+                        readonly type: "string";
+                    };
+                    readonly variant: {
+                        readonly type: "string";
+                    };
+                    readonly context: {
+                        readonly type: "string";
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly formats: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly path: {
+                                    readonly type: "string";
+                                };
+                                readonly width: {
+                                    readonly type: "integer";
+                                };
+                                readonly height: {
+                                    readonly type: "integer";
+                                };
+                            };
+                            readonly additionalProperties: true;
+                        };
+                    };
+                    readonly tags: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly additionalProperties: true;
+            };
+        };
+        readonly guidelines: {
+            readonly type: "object";
+            readonly description: "Usage guidelines";
+            readonly additionalProperties: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly content: {
+                        readonly type: "string";
+                    };
+                    readonly rules: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly $ref: "#/$defs/guidelineRule";
+                        };
+                    };
+                };
+                readonly additionalProperties: true;
+            };
+        };
+        readonly extensions: {
+            readonly type: "object";
+            readonly description: "Custom extensions";
+            readonly additionalProperties: true;
+        };
+    };
+    readonly additionalProperties: true;
+    readonly $defs: {
+        readonly guidelineRule: {
+            readonly type: "object";
+            readonly required: readonly ["description", "severity"];
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                };
+                readonly description: {
+                    readonly type: "string";
+                };
+                readonly severity: {
+                    readonly type: "string";
+                    readonly enum: readonly ["info", "warning", "error"];
+                };
+                readonly criteria: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly applies_to: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: true;
+        };
+    };
+};
+
+/**
+ * Extract all tokens as flat CSS custom properties.
+ *
+ * Output:
+ *   :root {
+ *     --primary: oklch(0.65 0.18 250);
+ *     --primary-foreground: oklch(0.98 0.01 250);
+ *     --font-heading: Inter, system-ui, sans-serif;
+ *     ...
+ *   }
+ */
+declare function toCss(data: BrandspecYaml): string;
+/**
+ * Generate a Tailwind v4 CSS import with theme tokens.
+ *
+ * Tailwind v4 uses CSS-based configuration:
+ *   @theme {
+ *     --color-primary: oklch(0.65 0.18 250);
+ *     --font-heading: Inter, system-ui, sans-serif;
+ *   }
+ */
+declare function toTailwindCss(data: BrandspecYaml): string;
+/**
+ * Generate Figma-compatible tokens JSON (Style Dictionary / Tokens Studio format).
+ */
+declare function toFigmaTokens(data: BrandspecYaml): string;
+/**
+ * Generate Style Dictionary token file (DTCG format) + config.
+ *
+ * Outputs two files:
+ *   tokens.json  — DTCG token definitions ($value, $type)
+ *   config.json  — Style Dictionary v4 config with common platforms
+ *
+ * Usage: `npx style-dictionary build --config config.json`
+ */
+declare function toStyleDictionary(data: BrandspecYaml): {
+    tokens: string;
+    config: string;
+};
+/** Flatten all tokens to a simple key-value map. */
+declare function flattenTokens(data: BrandspecYaml): Array<{
+    group: string;
+    name: string;
+    token: DesignToken;
+}>;
+
+declare const API_BASE: string;
+declare function getCredentialsPath(): string;
+declare function loadToken(): string | null;
+declare function parseOrgBrand(str: string): {
+    org: string;
+    brand: string;
+} | null;
+declare function loadRemote(args: string[]): {
+    org: string;
+    brand: string;
+} | null;
+declare function ensureBrandspecrc(org: string, brand: string): void;
+declare function saveCredentials(token: string): void;
+
+/**
+ * Lint engine for brand.yaml files.
+ * Ported from brandspec-tools SaaS — single source of truth.
+ */
+
+type LintSeverity = "error" | "warning" | "info";
+interface LintResult {
+    rule: string;
+    severity: LintSeverity;
+    message: string;
+    path?: string;
+}
+interface LintReport {
+    score: number;
+    results: LintResult[];
+    errors: number;
+    warnings: number;
+    infos: number;
+}
+declare function lintBrandspec(spec: BrandspecYaml): LintReport;
+
+/**
+ * Color utilities for brandspec lint rules.
+ * Ported from brandspec-tools SaaS — single source of truth.
+ */
+/** Parse hex, rgb(), or oklch() color string to [r, g, b] 0-255 */
+declare function parseColor(color: string): [number, number, number] | null;
+/** WCAG contrast ratio between two color strings */
+declare function getContrastRatio(color1: string, color2: string): number;
+
+export { API_BASE, type BrandspecAsset, type BrandspecCore, type BrandspecMeta, type BrandspecTokens, type BrandspecVoice, type BrandspecYaml, type DesignToken, type GuidelineRule, type GuidelineSection, type LintReport, type LintResult, type LintSeverity, type ParseResult, type ValidationResult, ensureBrandspecrc, flattenTokens, getContrastRatio, getCredentialsPath, lintBrandspec, loadRemote, loadToken, parse, parseColor, parseOrgBrand, saveCredentials, schema, serialize, toCss, toFigmaTokens, toStyleDictionary, toTailwindCss, validate };