Skip to content

define the docs visual brand fingerprint#246

Draft
nahiyankhan wants to merge 1 commit into
mainfrom
nahiyankhan/docs-visual-brand
Draft

define the docs visual brand fingerprint#246
nahiyankhan wants to merge 1 commit into
mainfrom
nahiyankhan/docs-visual-brand

Conversation

@nahiyankhan

Copy link
Copy Markdown
Collaborator

Category: improvement
User Impact: Agents receive a concrete, portable visual brand for extending ghost's documentation without falling back to generic AI-product styling.
Problem: The docs fingerprint mixed product, copy, CLI, and page-specific guidance while leaving the current visual expression underspecified. Agents had to infer foundational roles such as composition, color, type, spacing, card shape, meaningful accent use, motion, and specimen behavior from implementation details.
Solution: Replace the broad docs package with a cover-led visual-brand fingerprint grounded in the rendered docs source. The new package states global visual principles and exact system roles, adds conditional specimen and motion patterns, and consolidates review into one relationship-based fidelity check.

Validation:

  • pnpm check: passed
  • pnpm test: passed, 192 tests passed and 1 skipped
  • pnpm build: passed
  • node packages/ghost/dist/bin.js validate --package apps/docs/.ghost: passed with 0 errors, warnings, or info

Changeset: not needed because this only updates the private docs app's repo-local fingerprint and does not change the published package.

ghost Review:

  • ghost check --base origin/main: not run because this CLI version does not expose a check command; package validation passed instead.
  • ghost review --base origin/main --package apps/docs/.ghost: completed; no checks were offered because the diff only changes fingerprint files, which are intentionally not matched by the fingerprint's material locators.
File changes

apps/docs/.ghost/anti-goal.generated-docs-site.md
Removed the earlier generated-docs anti-goal in favor of a more specific visual replacement.

apps/docs/.ghost/anti-goal.generic-ai-product.md
Defines the generic AI-product median to reject and the marked-document expression that replaces it.

apps/docs/.ghost/asset.docs-materials.md
Removes the broad implementation inventory so concrete source references live with the guidance they substantiate.

apps/docs/.ghost/brand.md
Adds the manifest cover with the visual expression's non-negotiable relationships and escalation boundary.

apps/docs/.ghost/checks/cli-examples-match-manifest.md
Removes a product-documentation check outside this visual fingerprint's scope.

apps/docs/.ghost/checks/no-generic-ai-ornament.md
Replaces the narrow ornament check with a comprehensive visual fidelity check.

apps/docs/.ghost/checks/review-stays-advisory.md
Removes a product-model review check outside this visual fingerprint's scope.

apps/docs/.ghost/checks/visual-expression-fidelity.md
Adds one relationship-based check covering composition, visual-system roles, meaningful mark use, and applicable patterns.

apps/docs/.ghost/composition.md
Defines the global margin, reading-column, evidence-width, responsive-collapse, and active-space model.

apps/docs/.ghost/condition.cli-reference-exactness.md
Removes CLI-reference guidance outside this visual fingerprint's scope.

apps/docs/.ghost/decision.feed-forward-over-review.md
Removes a product-positioning decision outside this visual fingerprint's scope.

apps/docs/.ghost/exemplar.docs-site.md
Names the rendered docs as the source expression and separates governing relationships from incidental content.

apps/docs/.ghost/exemplar.home-thesis.md
Replaces the landing-copy exemplar with a medium-independent visual exemplar.

apps/docs/.ghost/glossary.md
Narrows the declared vocabulary to visual patterns, exemplars, and anti-goals while explaining the role of bare global nodes.

apps/docs/.ghost/index.md
Replaces the old all-purpose index with the manifest-declared visual-brand cover.

apps/docs/.ghost/manifest.yml
Gives the package a specific id and declares brand as its cover.

apps/docs/.ghost/mark.md
Defines yellow as a scarce record of selection, intervention, or active choice rather than decoration.

apps/docs/.ghost/pattern.doc-article.md
Removes the page-specific MDX article pattern from the visual fingerprint.

apps/docs/.ghost/pattern.docs-index-card-grid.md
Removes the route-specific docs index pattern from the visual fingerprint.

apps/docs/.ghost/pattern.landing-thesis.md
Removes the route-specific landing narrative pattern from the visual fingerprint.

apps/docs/.ghost/pattern.motion.md
Adds conditional guidance for motion that reveals order, selection, or structural change and respects reduced motion.

apps/docs/.ghost/pattern.specimen.md
Adds the bounded anatomy and responsive options for inspectable examples, tables, code, comparisons, palettes, and results.

apps/docs/.ghost/principle.product-model.md
Removes product-model guidance outside this visual fingerprint's scope.

apps/docs/.ghost/principle.visual-composition.md
Replaces the earlier high-level composition floor with separate global principles, composition, and visual-system chapters.

apps/docs/.ghost/principles.md
Adds global principles for visible structure, quiet hierarchy, nearby evidence, active space, and flat inspectable objects.

apps/docs/.ghost/visual-system.md
Defines color roles and contrast, mono type roles, spacing and responsive columns, squircle shape, flat elevation, control states, and accessibility behavior.

apps/docs/.ghost/voice.docs-language.md
Removes language guidance outside this visual fingerprint's scope.

Screenshots/Demos: N/A. This changes agent guidance, not the rendered docs surface.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant