@ideare/kit 0.0.0-stage → 0.1.0-next.0

package/dist/brand/schema.js

@@ -0,0 +1,271 @@
+import { z } from "zod";
+/**
+ * brand.json v1, the masters. Everything else (icons, cards, tokens, brand.md) is derived from
+ * this file by `generate()`, so a field belongs here only when a person chooses it. The kit
+ * outlines the wordmark and draws every file; neither is stored.
+ */
+export const BRAND_SCHEMA_VERSION = 1;
+export const BRAND_SCHEMA_URL = "https://ideare.app/schema/brand.v1.json";
+/** The languages a brand can write its copy in. Widening this list is not a breaking change. */
+export const LOCALES = ["pt-BR", "en", "es"];
+/** Every color role, in the order tokens and brand.md list them. */
+export const COLOR_ROLES = [
+    "ground",
+    "surface",
+    "ink",
+    "muted",
+    "line",
+    "primary",
+    "onPrimary",
+    "accent",
+    "onAccent",
+    "focus",
+    "danger",
+    "success",
+    "warning",
+];
+export const FONT_ROLES = ["display", "text"];
+/** The links a brand can list. `site` is a URL, the socials are handles, whatsapp is E.164. */
+export const LINK_KINDS = [
+    "site",
+    "instagram",
+    "facebook",
+    "x",
+    "linkedin",
+    "youtube",
+    "tiktok",
+    "whatsapp",
+    "email",
+    "phone",
+];
+/** The links that reach a person. ideare publishes them only when the owner shares contacts. */
+export const CONTACT_LINK_KINDS = ["whatsapp", "email", "phone"];
+const hex = z
+    .string()
+    .regex(/^#[0-9a-fA-F]{6}$/, "Use a 6-digit hex color, like #1A2B3C.")
+    .transform((value) => value.toLowerCase());
+const sha256 = z.string().regex(/^[0-9a-f]{64}$/, "Use a lowercase sha256 hex digest.");
+const svgMarkup = z
+    .string()
+    .max(65_536, "Keep the SVG under 64 KB.")
+    .refine((value) => /^\s*<svg[\s>]/.test(value), "Start the SVG with an <svg> element.");
+const locale = z.enum(LOCALES);
+const colorRole = z.enum(COLOR_ROLES);
+const paletteSchema = z.object(Object.fromEntries(COLOR_ROLES.map((role) => [role, hex])));
+const copySchema = z.object({
+    tagline: z.string().min(1).max(80),
+    description: z.string().min(1).max(300),
+    card: z.object({
+        title: z.string().min(1).max(70),
+        subtitle: z.string().max(140).optional(),
+    }),
+});
+const voiceSchema = z.object({
+    /** A few words for the tone, like "warm" or "direct". */
+    tone: z.array(z.string().min(1).max(40)).max(8),
+    /** Free notes for whoever writes in the brand's name. Private unless notesPublic. */
+    notes: z.string().max(2000).optional(),
+    notesPublic: z.boolean().default(false),
+    /** Words the brand never uses. The copy check flags them. */
+    neverSay: z.array(z.string().min(1).max(60)).max(60).default([]),
+    examples: z
+        .array(z.object({ context: z.string().min(1).max(60), text: z.string().min(1).max(400) }))
+        .max(20)
+        .default([]),
+});
+const tileSchema = z.object({
+    /** The color role behind the mark on icons and avatars. */
+    fill: colorRole.default("primary"),
+    shape: z.enum(["square", "rounded", "circle"]).default("rounded"),
+    /** Corner radius as a fraction of the tile's side (rounded only). */
+    radius: z.number().min(0).max(0.5).default(0.22),
+    /** Space around the mark as a fraction of the tile's side. */
+    padding: z.number().min(0).max(0.4).default(0.18),
+});
+const markSchema = z.object({
+    svg: svgMarkup,
+    /** A simpler drawing for 16 to 32 px. Falls back to svg. */
+    small: svgMarkup.optional(),
+    /** The version for dark grounds. Falls back to svg with the darkest color swapped. */
+    dark: svgMarkup.optional(),
+    /**
+     * The owner's own logo versions, drawn as they are instead of composed from the mark and the
+     * wordmark: a brand brought in from its files keeps the lockups it already has. Each one's
+     * viewBox hugs the drawing.
+     */
+    lockups: z
+        .object({
+        horizontal: svgMarkup.optional(),
+        stacked: svgMarkup.optional(),
+        wordmark: svgMarkup.optional(),
+    })
+        .optional(),
+    tile: tileSchema.prefault({}),
+    /** Where the mark came from. Icon marks come from an open set, so they are not exclusive. */
+    source: z
+        .object({
+        kind: z.enum(["monogram", "icon", "ai", "upload"]),
+        /** For icon marks: the set and name, like "lucide:scissors". */
+        ref: z.string().max(80).optional(),
+    })
+        .optional(),
+});
+const wordmarkSchema = z.object({
+    text: z.string().min(1).max(40),
+    font: z.enum(FONT_ROLES).default("display"),
+    weight: z.number().int().min(100).max(900).default(700),
+    /** Letter spacing in em, like -0.02. */
+    tracking: z.number().min(-0.2).max(0.5).default(0),
+});
+const fontSchema = z.object({
+    /** The family name people see, like "Instrument Sans". Letters, digits, spaces and . ' & -
+     *  only: it is written into CSS and HTML, so a quote or a brace could end the string there. */
+    family: z
+        .string()
+        .min(1)
+        .max(80)
+        .regex(/^[\p{L}\p{N} .'&-]+$/u, "Use the font's name, like Instrument Sans."),
+    /** The Fontsource id, like "instrument-sans". */
+    id: z.string().regex(/^[a-z0-9-]+$/, "Use the Fontsource id, like instrument-sans."),
+    weights: z.array(z.number().int().min(100).max(900)).min(1).max(9),
+    license: z.enum(["OFL-1.1", "Apache-2.0"]),
+    /** sha256 of each weight's TTF, keyed by weight. Written by the kit when it fetches them. */
+    files: z.record(z.string().regex(/^[1-9]00$/), sha256).default({}),
+});
+const radiiSchema = z.object({
+    /** Buttons and fields, in px. */
+    control: z.number().min(0).max(64).default(10),
+    /** Cards and panels, in px. */
+    card: z.number().min(0).max(64).default(16),
+});
+const artSchema = z.object({
+    /** The style every AI picture follows. */
+    prompt: z.string().max(2000).default(""),
+    references: z
+        .array(z.object({
+        sha256,
+        mime: z.enum(["image/png", "image/jpeg", "image/webp"]),
+        width: z.number().int().positive(),
+        height: z.number().int().positive(),
+    }))
+        .max(10)
+        .default([]),
+    referencesPublic: z.boolean().default(false),
+    avoid: z.array(z.string().min(1).max(80)).max(30).default([]),
+});
+const linkSchema = z.object({
+    value: z.string().min(1).max(300),
+    /** Shown in the public brand.json and brand page only when ticked. */
+    public: z.boolean().default(false),
+});
+const linksShape = Object.fromEntries(LINK_KINDS.map((kind) => [kind, linkSchema.optional()]));
+export const brandSchema = z
+    .object({
+    $schema: z.literal(BRAND_SCHEMA_URL).default(BRAND_SCHEMA_URL),
+    schemaVersion: z.literal(BRAND_SCHEMA_VERSION),
+    /** The public address part, ideare.app/b/<slug>. Set by ideare on the first approval. */
+    slug: z
+        .string()
+        .regex(/^[a-z0-9](?:[a-z0-9-]{0,46}[a-z0-9])?$/)
+        .optional(),
+    /** The approved version this file came from. Absent on drafts. */
+    version: z.number().int().positive().optional(),
+    name: z.string().min(1).max(60),
+    /** For tight spots: the app name under a home-screen icon. */
+    shortName: z.string().min(1).max(12),
+    domain: z
+        .string()
+        .regex(/^(?:[a-z0-9-]+\.)+[a-z]{2,}$/, "Use a bare domain, like padaria.com.br.")
+        .optional(),
+    locales: z.array(locale).min(1),
+    defaultLocale: locale,
+    copy: z.partialRecord(locale, copySchema),
+    voice: voiceSchema.prefault({ tone: [] }),
+    mark: markSchema,
+    wordmark: wordmarkSchema,
+    colors: z.object({ light: paletteSchema, dark: paletteSchema }),
+    /**
+     * Extra named colors for illustrations, bands and accents, like "peach" or "trio-red".
+     * They never take a role: text and controls use `colors`.
+     */
+    paints: z
+        .record(z
+        .string()
+        .regex(/^[a-z][a-z0-9-]{0,31}$/, "Name a paint in lowercase, like peach or trio-red."), hex)
+        .default({}),
+    fonts: z.object({ display: fontSchema, text: fontSchema }),
+    radii: radiiSchema.prefault({}),
+    art: artSchema.prefault({}),
+    links: z.object(linksShape).default({}),
+})
+    .superRefine((brand, ctx) => {
+    if (new Set(brand.locales).size !== brand.locales.length) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["locales"],
+            message: "List each language once.",
+        });
+    }
+    if (!brand.locales.includes(brand.defaultLocale)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["defaultLocale"],
+            message: "The default language must be one of the brand's languages.",
+        });
+    }
+    for (const lang of brand.locales) {
+        if (!brand.copy[lang]) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["copy", lang],
+                message: `Add the copy for ${lang}, or take ${lang} out of locales.`,
+            });
+        }
+    }
+    for (const lang of Object.keys(brand.copy)) {
+        if (!brand.locales.includes(lang)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["copy", lang],
+                message: `${lang} has copy but is not in locales.`,
+            });
+        }
+    }
+});
+/**
+ * Read a brand.json. A file from a newer kit is refused with "Update ideare" instead of being
+ * half-read, so a CLI never writes files from a format it does not know.
+ */
+export function parseBrand(input) {
+    const declared = typeof input === "object" && input !== null && "schemaVersion" in input
+        ? input.schemaVersion
+        : undefined;
+    if (typeof declared === "number" && declared > BRAND_SCHEMA_VERSION) {
+        return {
+            ok: false,
+            reason: "newer",
+            issues: [
+                {
+                    path: "schemaVersion",
+                    message: `This brand.json is format ${declared}, and this ideare reads up to ${BRAND_SCHEMA_VERSION}. Update ideare.`,
+                },
+            ],
+        };
+    }
+    const result = brandSchema.safeParse(input);
+    if (result.success)
+        return { ok: true, brand: result.data };
+    return {
+        ok: false,
+        reason: "invalid",
+        issues: result.error.issues.map((issue) => ({
+            path: issue.path.map(String).join(".") || "(root)",
+            message: issue.message,
+        })),
+    };
+}
+/** The JSON Schema for editors and outside tools, generated from the zod schema. */
+export function brandJsonSchema() {
+    const schema = z.toJSONSchema(brandSchema, { io: "input", unrepresentable: "any" });
+    return { ...schema, $id: BRAND_SCHEMA_URL, title: "ideare brand.json v1" };
+}

package/dist/check/copy.d.ts

@@ -0,0 +1,27 @@
+import type { Locale } from "../brand/schema.ts";
+/**
+ * The copy check: the house rules for every word a person reads, run on the brand's own copy.
+ * No em dash, none of the words that make text read as written by a machine, sentence case, no
+ * exclamation marks, and lengths that fit where the words go.
+ */
+export type CopyField = "tagline" | "title" | "subtitle" | "description";
+export type CopyIssue = {
+    rule: "emDash" | "dashBreak" | "bannedWord" | "exclamation" | "sentenceCase" | "length" | "spacing";
+    level: "error" | "warning";
+    message: string;
+    details?: Record<string, string | number>;
+};
+/** Words and phrases that read as machine-written, per language, without accents. */
+export declare const BANNED_WORDS: Record<Locale, string[]>;
+/** Where each field shows, and how much fits there. */
+export declare const COPY_LIMITS: Record<CopyField, number>;
+/**
+ * Check one piece of copy. `names` are words allowed to start with a capital anywhere (the brand
+ * name, places); `neverSay` is the brand's own list.
+ */
+export declare function checkCopy(text: string, options: {
+    locale: Locale;
+    field: CopyField;
+    neverSay?: string[];
+    names?: string[];
+}): CopyIssue[];

package/dist/check/copy.js

@@ -0,0 +1,139 @@
+/** Words and phrases that read as machine-written, per language, without accents. */
+export const BANNED_WORDS = {
+    en: [
+        "unlock",
+        "elevate",
+        "seamless",
+        "seamlessly",
+        "effortless",
+        "effortlessly",
+        "empower",
+        "leverage",
+        "robust",
+        "comprehensive",
+        "cutting-edge",
+        "delve",
+        "game-changing",
+        "game changer",
+        "next-level",
+        "revolutionize",
+        "revolutionary",
+        "supercharge",
+        "unleash",
+        "synergy",
+        "in today's fast-paced world",
+        "designed to help you",
+    ],
+    "pt-BR": [
+        "revolucionario",
+        "revolucionar",
+        "alavancar",
+        "potencializar",
+        "sem esforco",
+        "de ponta",
+        "desbloquear",
+        "sinergia",
+        "no mundo acelerado de hoje",
+        "projetado para ajudar",
+        "eleve o seu",
+        "eleve sua",
+    ],
+    es: [
+        "revolucionario",
+        "revolucionar",
+        "potenciar",
+        "sin esfuerzo",
+        "de vanguardia",
+        "desbloquear",
+        "sinergia",
+        "apalancar",
+        "en el mundo acelerado de hoy",
+        "disenado para ayudarte",
+    ],
+};
+/** Where each field shows, and how much fits there. */
+export const COPY_LIMITS = {
+    tagline: 60,
+    title: 60,
+    subtitle: 110,
+    description: 160,
+};
+function plain(text) {
+    return text.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+}
+function hasWord(haystack, needle) {
+    const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[^\\p{L}\\p{N}])${escaped}($|[^\\p{L}\\p{N}])`, "u").test(haystack);
+}
+/**
+ * Check one piece of copy. `names` are words allowed to start with a capital anywhere (the brand
+ * name, places); `neverSay` is the brand's own list.
+ */
+export function checkCopy(text, options) {
+    const issues = [];
+    if (text.includes("\u2014")) {
+        issues.push({
+            rule: "emDash",
+            level: "error",
+            message: "Take out the long dash. Use a period, a comma or a colon.",
+        });
+    }
+    if (/\s[\u2013-]\s/.test(text)) {
+        issues.push({
+            rule: "dashBreak",
+            level: "warning",
+            message: "A dash between spaces reads like a pause. Use a period, a comma or a colon.",
+        });
+    }
+    if (/[!¡]/.test(text)) {
+        issues.push({
+            rule: "exclamation",
+            level: "error",
+            message: "Take out the exclamation mark. Calm words read as more sure.",
+        });
+    }
+    const flat = plain(text);
+    const banned = [...BANNED_WORDS[options.locale], ...(options.neverSay ?? []).map(plain)];
+    const found = [...new Set(banned.filter((word) => hasWord(flat, plain(word))))];
+    if (found.length) {
+        issues.push({
+            rule: "bannedWord",
+            level: "error",
+            message: `Say it in plain words instead of "${found.join('", "')}".`,
+            details: { words: found.join(", ") },
+        });
+    }
+    if (/\s{2,}|^\s|\s$/.test(text)) {
+        issues.push({ rule: "spacing", level: "warning", message: "Remove the extra spaces." });
+    }
+    // Sentence case: after the first word, only names and acronyms start with a capital. Three
+    // or more capitals that are not names, making most of the words, read as Title Case.
+    if (options.field !== "description") {
+        const names = new Set((options.names ?? []).flatMap((name) => name.split(/\s+/)).map(plain));
+        const words = text
+            .split(/\s+/)
+            .slice(1)
+            .map((word) => word.replace(/^[^\p{L}]+|[^\p{L}]+$/gu, ""))
+            .filter((word) => word.length >= 2 && !names.has(plain(word)) && word !== word.toUpperCase());
+        const capitalized = words.filter((word) => /^\p{Lu}/u.test(word));
+        if (capitalized.length >= 3 && capitalized.length >= words.length * 0.6) {
+            issues.push({
+                rule: "sentenceCase",
+                level: "warning",
+                message: "Use sentence case: only the first word and names start with a capital letter.",
+                details: { words: capitalized.join(", ") },
+            });
+        }
+    }
+    const limit = COPY_LIMITS[options.field];
+    const length = [...text].length;
+    if (length > limit) {
+        issues.push({
+            rule: "length",
+            level: "warning",
+            message: `This is ${length} characters; about ${limit} fit where it shows. Shorten it a little.`,
+            details: { length, limit },
+        });
+    }
+    return issues;
+}

package/dist/check/index.d.ts

@@ -0,0 +1,54 @@
+import type { Brand } from "../brand/schema.ts";
+import type { CardPage, DerivedFile } from "../files/generate.ts";
+import type { Rasterizer } from "../files/raster.ts";
+import type { FontResolver } from "../text/fonts.ts";
+/**
+ * check(): every promise a brand kit makes, measured. Each result has a plain title an owner
+ * reads ("Easy to read", "Hard to read on cards: fix it"), the numbers behind it for "Details",
+ * and, when one exists, a fix the studio shows before and after and applies only on a tap.
+ */
+export type CheckLevel = "pass" | "warning" | "error";
+export type CheckFix = 
+/** Set these brand.json fields. `from` is there so the studio can show before and after. */
+{
+    kind: "set";
+    label: string;
+    changes: {
+        path: string;
+        from: unknown;
+        to: unknown;
+    }[];
+}
+/** Ask for new words (the "Write it again" button). */
+ | {
+    kind: "rewrite";
+    label: string;
+    path: string;
+};
+export type CheckResult = {
+    /** Stable, for translations and tests: like "contrast.light.muted.surface". */
+    id: string;
+    area: "colors" | "logo" | "text" | "fonts" | "files" | "copy";
+    level: CheckLevel;
+    title: string;
+    message?: string;
+    fix?: CheckFix;
+    details?: Record<string, string | number>;
+};
+export type CheckContext = {
+    /** Needed for text fit and glyph coverage. Without it those checks are skipped, and say so. */
+    fonts?: FontResolver;
+    /** Lets the 16 px legibility check look at real pixels. */
+    rasterize?: Rasterizer;
+    /** Made files, for the size limits. */
+    files?: Map<string, DerivedFile>;
+    pages?: CardPage[];
+};
+/** Run every check. Errors come first, then warnings, then what passed. */
+export declare function check(brand: Brand, ctx?: CheckContext): Promise<CheckResult[]>;
+/** "2 to fix" and friends, for the folded summary. */
+export declare function summarize(results: CheckResult[]): {
+    errors: number;
+    warnings: number;
+    passed: number;
+};