Skip to content

bug(docs): align Quick Start usage with generated token names and output paths #23

Description

@Hebilicious

Problem

The Quick Start configuration and its consumption examples still disagree in README.md at 94bf4d8.

The configuration defines coral.100, mint.100, and indigo.100 palette entries, plus spacing.custom.size.1 through 4. However, the example consumes:

@import "cssforge.output.css" layer(cssforge);

.button {
  background-color: var(--color-primary-500);
  padding: var(--size-2) var(--size-4);
}

The generated spacing declarations use --spacing-size-*, and the configuration has no primary.500 token. The TypeScript usage comment likewise references cssForge.colors.palette.basic.white, which is not produced by this configuration. The CSS import filename also differs from the CLI's documented default ./.cssforge/output.css.

Expected behavior

A consumer should be able to follow the Quick Start from installation through generation and consumption without inventing missing tokens, renaming output files, or correcting generated-object paths.

For example, with the documented palette and spacing configuration, the CSS consumption should use:

/* Relative to a consumer stylesheet placed at the project root. */
@import "./.cssforge/output.css" layer(cssforge);

.button {
  background-color: var(--palette-coral-100);
  padding: var(--spacing-size-2) var(--spacing-size-4);
}

Derive the TypeScript consumption example from the actual generated module rather than guessing its object shape.

Acceptance criteria

  • Store the Quick Start config and CSS/TypeScript consumption examples as executable fixtures, or extract and validate the actual README snippets.
  • Run generation against that exact configuration; assert every CSS token used by the example is declared.
  • Type-check a real property access on the generated TypeScript output, not just an explanatory comment.
  • Make output paths, generated filenames, and stylesheet placement explicit and consistent.
  • Run the documented flow in a clean consumer project, integrating with the packed-artifact tests in chore(distribution): make npm the primary release channel and keep JSR as fallback #22.
  • Propagate the correction through the existing generated package README, documentation pages, and agent-facing outputs.

Relationship to existing work

#21 already added generated-documentation synchronization/enforcement. This issue is a remaining semantic correctness gap in the Quick Start, not a request to rebuild or replace that pipeline. Installation and import-specifier changes belong to #22.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions