JQ AI SYSTEMS Design System

Start Here

Pick the job, then use the system.

The design system is long by design. These paths turn it into a working tool for common website and content tasks.

Build a page

Start from a recipe

Use the page recipes for section order, metadata, CTA hierarchy, and proof expectations.

Use assets

Pick the right logo

Choose the official logo file for dark, light, social, document, or compact UI use.

Write copy

Keep it builder-led

Use practical, specific language with clear sources and no generic AI hype.

Create images

Use brand-safe prompts

Follow the AI image workflow for prompts, dimensions, logo placement, and source links.

Foundations

Same brand DNA, dark-mode system.

The website keeps the typography, teal-blue accent system, and designer-led restraint from the main Joao Queiros brand, then adapts it for AI systems content.

Principle

Designer-built systems

The site should feel like a dark-mode extension of Joao Queiros brand work: calm, editorial, precise, and useful rather than loud or generic.

Layout

Wide but controlled

Use the global 1200px wrap, full-width bands, restrained 8px-or-less radii, and grid layouts that collapse cleanly to one column.

Motion

Subtle reveal, never dependency

Scroll reveal, video, and hover lift can add polish, but reduced-motion and mobile first-paint states must still show complete content.

AI Ready

Clear sources of truth

Every page should expose clear metadata, canonical URLs, practical copy, and enough context for humans and AI systems to cite accurately.

Tokens

Brand colors and runtime aliases.

The official asset colors and the live website tokens are intentionally documented separately so future edits do not accidentally rewrite the whole visual system.

Official Brand Colors

Use these when producing JQ AI SYSTEMS logos, social images, AI image prompts, source files, and external brand materials.

brand.teal Teal Green #00A79D

brand.cyan Bright Cyan Blue #0095DA

brand.charcoal Deep Charcoal #0D1114

brand.gradient Brand Gradient linear-gradient(90deg,#00A79D 0%,#0095DA 100%)

Runtime Website Tokens

These are the live CSS variables currently used by the website. Keep them stable unless the whole site is being realigned.

--bg Page Background #111110

--bg-surface Surface #1A1A18

--bg-card Card #1F1F1D

--teal Website Teal #00A89D

--blue Website Blue #0099D6

--text Primary Text #F5F5F0

--text-body Body Text #A3A39F

--text-muted Muted Text #6B6B68

Semantic Color Roles

Use semantic roles in new scoped CSS so page intent stays readable even if the runtime aliases are realigned later.

surface.page Page Surface var(--bg) / #111110

surface.panel Raised Surface rgba(22,24,26,.56)

text.primary Primary Text var(--text) / #F5F5F0

text.secondary Secondary Text var(--text-body) / #A3A39F

action.primary Primary Action var(--grad)

border.default Default Border rgba(232,232,227,.08)

border.accent Accent Border rgba(0,168,157,.22)

focus.ring Focus Ring 2px solid var(--teal)

Spacing Rhythm

Use a small, predictable spacing scale. Prefer section rhythm and grid gaps over one-off margins.

space.1 Space 1 .35rem / 6px

space.2 Space 2 .65rem / 10px

space.3 Space 3 1rem / 16px

space.4 Space 4 1.5rem / 24px

space.5 Space 5 2rem / 32px

space.6 Space 6 3rem / 48px

space.section Section Gap clamp(4rem,8vw,6.5rem)

space.grid Grid Gap 1rem to 1.4rem

Shape, Elevation, Motion, Breakpoints

These tokens keep UI surfaces quiet, stable, and easy to scan on both desktop and mobile.

radius.control Control Radius 4px

radius.panel Panel Radius 8px max

elevation.soft Soft Elevation 0 30px 90px rgba(0,0,0,.34)

motion.lift Hover Lift translateY(-2px)

motion.duration Duration var(--dur)

motion.ease Ease var(--ease)

breakpoint.tablet Tablet 980px

breakpoint.mobile Mobile 768px

Heading font	Libre Baskerville for editorial authority, page hierarchy, and the visual link to the main Joao Queiros brand.
Body font	Inter for UI, navigation, cards, forms, and long-form readability.
Mono font	JetBrains Mono for tokens, metadata, code snippets, technical labels, and copyable prompts.
Layout width	Use `--max-w: 1200px` with `.wrap`; full-width sections should use bands, not floating page cards.
Radius	Use 4px for buttons and controls, 6px for code and small frames, and 8px for cards or large resource panels.

Identity

Logo usage that stays boringly correct.

Use the official files from Brand Assets. Never redraw, stretch, crop, recolor, or use logo-like text as a substitute.

dark / social / image overlay

Horizontal Reversed

Default for dark website sections, photographic images, video thumbnails, and GPT Image prompts.

light / documents / proposals

Horizontal Full Color

Default for white decks, proposals, invoices, one-pagers, PDFs, and light editorial layouts.

avatar / compact mark

Symbol Gradient

Use when the full wordmark is too large: favicons, avatars, overlays, and small repeated UI references.

Official Source

Download logos and source files from Brand Assets.

PNG is practical for image tools. SVG is preferred for websites, Figma, Illustrator, and anything that needs clean scaling.

Open Brand Assets

Components

Reusable pieces for fast page builds.

These are behavior-level rules for the existing PHP/CSS site. Keep new component CSS page-scoped unless the component is needed across several pages.

Component

Buttons

Use primary gradient buttons for the main action, teal outline buttons for secondary actions, and plain text links inside prose.

Avoid: Avoid three equally loud CTAs in the same view.

Default
Hover
Focus
Disabled

<a class="btn btn-primary" href="/contact">Primary Action</a> <a class="btn btn-teal" href="/library">Secondary Action</a>

Component

Section Headers

Use an overline, a serif heading, and one short support paragraph. Split headers work when the support copy needs a scanning lane.

Avoid: Avoid feature explanations inside the heading itself.

Default
Split
Compact

<div class="section-header-split"><div><span class="overline">System</span><h2>Readable structure first.</h2></div><p>One practical support paragraph.</p></div>

Component

Cards

Cards are for repeated items, resources, tools, examples, and framed previews. Avoid placing cards inside cards.

Avoid: Avoid using cards as full page sections.

Default
Hover
Resource
Callout

<article class="design-system-card"><span class="design-system-kicker">Token</span><h3>Card title</h3><p>Short useful explanation.</p></article>

Component

Forms

Use visible labels, focused field states, single-column mobile layouts, and plain helper copy that explains the required input.

Avoid: Avoid placeholder-only labels.

Default
Focus
Helper
Error

<div class="form-group"><label for="example">Project context</label><textarea id="example" placeholder="What should the system do?"></textarea></div>

Component

Prompt Panels

Use copy panels when the user needs reusable implementation text, prompts, metadata, or AI-ready source instructions.

Avoid: Avoid hiding source-of-truth text behind images or modals.

Ready
Copied
Fallback

<button type="button" class="brand-download" data-copy-target="snippet" data-copy-status="snippet-status">Copy snippet</button>

Component

Accordions

Use native details/summary for FAQ, checklists, and optional implementation notes.

Avoid: Avoid custom disclosure controls without keyboard behavior.

Closed
Open
Focus

<details><summary>What changes when tokens move?</summary><p>Update the design system and source references together.</p></details>

Component

Tables

Use tables for token comparisons, source-of-truth maps, and compact governance references.

Avoid: Avoid tables for marketing copy or card-like content.

Desktop
Stacked mobile
Readable labels

<table><tr><th>Source</th><td>css/style.css</td></tr></table>

Component

CTA Bands

Use full-width bands for primary conversion moments, with one main action and one optional secondary link.

Avoid: Avoid placing a CTA card inside another visual card.

Primary
Proof-led
Resource-led

<section class="section section-dark"><div class="wrap"><a class="btn btn-primary" href="/contact">Start</a></div></section>

Live Preview

Component states and previews

These previews show the default shapes to reuse when building new pages. They stay static and semantic, with native controls where possible.

Buttons

Action hierarchy

Use one primary action, one secondary action, and plain links in prose.

Book Consultation Browse Library Disabled

Forms

Label, helper, error

Disclosure

Native accordion

When should tokens be updated?

Update the public page, source CSS, prompt guidance, and maintainer note together when the change affects reuse.

What stays page-scoped?

One-off previews and design-system-only layout styles stay inside this page.

Category chips

Keep tags short and scannable.

Systems Prompting Brand Assets AEO

Resource Card

Useful, not decorative

Public resource

AI Image Prompt Kit

Use when the page needs repeatable prompt, image, and asset guidance.

Open prompt kit

CTA Band

One conversion job

Use one main action and one optional secondary path.

Start a System Brand assets

Patterns

Page structures with clear jobs.

Each page type should make its purpose obvious quickly, then support scanning, trust, conversion, and machine-readable context.

Pattern

Home Hero

Use one strong first-viewport signal, concise value copy, proof stats, and real video or image depth.

Pattern

Service Page

Lead with the business outcome, show fit and process, then push to a scoped contact or intake action.

Pattern

System Case Study

Show problem, workflow, proof, owned deliverables, and public-safe screenshots or diagrams.

Pattern

Blog Post

Use practical builder-led argument, citations where needed, related posts, and clear next action.

Pattern

Library/Search

Favor scan speed: tags, short descriptions, stable cards, and visible search or browse paths.

Pattern

Resource Page

Make downloads and source-of-truth rules obvious; use copyable snippets when reuse matters.

Page Recipes

Reusable page structures with known decisions.

Use these recipes when creating new public pages so the implementer does not have to rediscover section order, CTA priority, metadata, and proof rules.

Recipe

Service Page

Section order: Hero, fit, outcomes, process, proof, FAQ, CTA.
CTA: Primary: contact or intake. Secondary: relevant library/resource.
Metadata: Canonical URL, service title, factual description, service schema when appropriate.
Proof: Use concrete deliverables, workflow screenshots, public-safe examples, or bounded case notes.

Recipe

System Case Study

Section order: Problem, constraints, build approach, workflow, result, reusable lessons, next step.
CTA: Primary: discuss a similar system. Secondary: browse systems or related post.
Metadata: WebPage schema plus sanitized entities and dates. Do not expose client-private details.
Proof: Show artifacts, diagrams, before/after states, or measurable outcomes only when approved.

Recipe

Blog Post

Section order: Thesis, context, practical steps, examples, caveats, FAQ, related posts.
CTA: Primary: relevant resource or contact. Secondary: library/search.
Metadata: Post registry, canonical, OG image, dates, FAQ schema when useful, related links.
Proof: Cite sources where needed and avoid unverified benchmarks or trend claims.

Recipe

Resource / Tool Page

Section order: Purpose, who it is for, assets/snippets, usage rules, related resources, maintenance note.
CTA: Primary: download/copy/use. Secondary: contact for custom work.
Metadata: Resource title, canonical, breadcrumb, llms summary, sitemap entry for public resources.
Proof: Make file names, source relationships, and reuse limits explicit.

Recipe

Intake / Contact Flow

Section order: Fit statement, form, expected reply, privacy boundary, alternative contact, FAQ.
CTA: Primary: submit inquiry. Secondary: email or browse work.
Metadata: Clear page title, no invented response promises, analytics category, contact schema if used.
Proof: Explain what information is needed and what will not be shared publicly.

Voice

Practical, specific, builder-led.

The writing should sound like a designer and systems builder explaining real work, not like a generic AI product page.

Rules

Content defaults

Use a practical, builder-led JQ AI SYSTEMS voice.
Avoid generic AI hype, vague transformation language, and fake certainty.
Do not invent product facts, dates, benchmarks, prices, credentials, or claims.
Explain what the system does, who it helps, what is owned by the client, and what is still a limitation.
Keep CTAs concrete: consultation, intake, library, brand assets, prompt kit, or contact.
Write for humans first, but keep entities, URLs, filenames, and relationships easy for AI systems to parse.

AI Image Workflow

Brand-safe image production, without fake details.

Use official assets as references, keep generated visuals honest, and make every image easy to reuse across website, social, and search surfaces.

Sizes

Default outputs

OG and link preview: 1200x630.
Square social proof: 1080x1080.
Portrait social post: 1080x1350.
Website banners: crop from a larger horizontal source when possible.

Rules

Production checklist

Use 1200x630 for OG/social share images and keep important text or logos away from the outer 80px safe zone.
Use 1080x1080 for square proof posts and 1080x1350 for portrait social posts when the subject needs more vertical space.
Use the reversed horizontal logo on dark or photographic backgrounds and the full-color horizontal logo on light backgrounds.
Use the symbol mark only when the full wordmark would become too small to read.
Never ask an image model to redraw the logo from memory; provide or reference the official Brand Assets files.
Repeat critical text in HTML or post copy. Do not rely on small generated text inside images.

Sources

Use the public tools

Start with the official logo files, then use the prompt kit for branded and no-logo image instructions.

Brand Assets Prompt Kit

Default prompt stance

Images should support the page, not invent product evidence. If the visual includes interface screens, metrics, client names, or claims, those details must come from an approved source and be repeated in nearby HTML or caption copy.

Accessibility

Dark, cinematic, still usable.

The site can be visually rich without making the content fragile. Accessibility is part of the system, not a late checklist.

Body text on page background

#A3A39F on #111110

Pass target

Use for paragraphs, captions, and long descriptions.

Muted metadata

#6B6B68 on #111110

Use carefully

Keep small muted text non-critical or raise contrast for important labels.

Primary action

Gradient button with white text

Check per use

Test the lightest gradient point under the exact text size.

Focus states

Visible ring or strong border shift

Required

Links, buttons, summaries, and fields must show keyboard focus.

Targets

At least 44px where practical

Required

Especially for jump links, copy buttons, cards, and mobile CTAs.

Motion

Reduced-motion content remains complete

Required

Video and reveal effects cannot be required for comprehension.

Mobile text fit

No horizontal overflow or clipped labels

Required

Long token names and copy buttons must wrap cleanly.

Images and video

Informative alt text, decorative hidden video

Required

Do not bake essential text into generated images only.

Publish Checklist

Run before a public page goes live

Run php -l on edited PHP files.
Check desktop and mobile widths for overlap, overflow, and readable copy panels.
Tab through links, buttons, forms, summaries, and copy controls.
Verify canonical URL, page title, description, OG image, and JSON-LD.
Update sitemap and llms.txt when a new public resource is added.
Keep claims factual, dated when needed, and backed by a visible source or owned proof.
Confirm links to Brand Assets, Prompt Kit, Library, Contact, and related pages.
Use official logo files and document any non-default asset choice.

This matrix is a working checklist, not a formal WCAG audit. Use browser, keyboard, contrast, and mobile checks before claiming accessibility quality.

A11y

Rule 1

Keep visible focus states on links, buttons, form fields, summary elements, and custom controls.

A11y

Rule 2

Use actual text for important content, not text baked into images unless it is also repeated in HTML.

A11y

Rule 3

Respect reduced motion and data saver: decorative video must not be required for comprehension.

A11y

Rule 4

Avoid text overlap at mobile widths; cards and buttons should wrap instead of shrinking into unreadable text.

A11y

Rule 5

Give meaningful alt text to informative images and empty or hidden treatment to decorative video.

A11y

Rule 6

Check dark-mode contrast for body text, muted text, borders, and teal-on-dark actions.

Governance

Keep the system in sync.

The design system documents the live website. When one source changes, the related public references should move with it.

Version

Design System v1.0 Last updated: 2026-06-25 Public URL: /design-system

Version this public guidance when token groups, component rules, page recipes, accessibility checks, or source-of-truth relationships materially change.

Sources of truth

Update these together when their responsibilities overlap

css/style.css	Runtime tokens, shared components, layout rhythm, global focus styles. Update: When global styles or shared tokens change.
brand-assets.php	Logo files, official brand colors, downloads, asset language. Update: When logo guidance or downloadable assets change.
ai-image-prompt-kit.php	Prompt conventions, image sizes, no-logo and branded image rules. Update: When AI image workflow guidance changes.
includes/head-meta.php	Metadata defaults, fonts, critical CSS token assumptions. Update: When SEO/OG/favicons/font loading changes.
_docs/generate-sitemap.php	Sitemap URL source list for public static routes. Update: When public routes are added or removed.
llms.txt	AI-readable public resource map. Update: When important public resources or canonical summaries change.

Snippets

Copy-ready source references.

Use these when adding pages, prompts, or tokens. They mirror the current website rather than proposing a redesign.

CSS

Runtime token block

:root {
  --bg: #111110;
  --bg-surface: #1A1A18;
  --bg-card: #1F1F1D;
  --teal: #00A89D;
  --blue: #0099D6;
  --grad: linear-gradient(135deg, #00A89D 0%, #0099D6 100%);
  --text: #F5F5F0;
  --text-body: #A3A39F;
  --text-muted: #6B6B68;
  --border: rgba(232, 232, 227, 0.08);
  --max-w: 1200px;
}

Ready to copy

CSS

Semantic aliases

/* Page-scoped semantic aliases for new JQ AI SYSTEMS pages */
.page-scope {
  --surface-page: var(--bg);
  --surface-panel: rgba(22, 24, 26, 0.56);
  --surface-card: var(--bg-card);
  --text-primary: var(--text);
  --text-secondary: var(--text-body);
  --text-subtle: var(--text-muted);
  --action-primary: var(--grad);
  --border-default: var(--border);
  --border-accent: rgba(0, 168, 157, 0.22);
}

Ready to copy

JSON

Token exchange sketch

{
  "brand": {
    "teal": "#00A79D",
    "cyan": "#0095DA",
    "charcoal": "#0D1114"
  },
  "runtime": {
    "bg": "#111110",
    "teal": "#00A89D",
    "blue": "#0099D6",
    "text": "#F5F5F0"
  },
  "semantic": {
    "surface.page": "var(--bg)",
    "text.primary": "var(--text)",
    "action.primary": "var(--grad)",
    "border.default": "var(--border)"
  }
}

Ready to copy

PHP

Page metadata shell

<?php
require __DIR__ . '/includes/bootstrap.php';

$current_page     = 'page-slug';
$page_ga_type     = 'resource';
$page_ga_category = 'resources';
$page_title       = 'Page Title | JQ AI SYSTEMS';
$page_description = 'One specific, factual description of the page.';
$page_canonical   = 'https://www.ai.joaoqueiros.com/page-slug';
$page_image       = 'https://www.ai.joaoqueiros.com/images/og/og-brand-assets.png';
?>

Ready to copy

Prompt

Brand asset instruction

Use the official JQ AI SYSTEMS brand assets from https://www.ai.joaoqueiros.com/brand-assets. For dark or photographic posts, use jqai-horizontal-reversed. For light layouts, use jqai-horizontal-full-color. For compact icons, use jqai-symbol-gradient-transparent. Preserve clear space and never stretch, redraw, crop, recolor, or alter the logo.

Ready to copy

Prompt

AI image production prompt

Create a JQ AI SYSTEMS website/social image using the official brand system:
- Dark cinematic technical surface, practical builder-led tone, teal-to-blue accents.
- Use official logo files from https://www.ai.joaoqueiros.com/brand-assets; do not redraw the logo.
- Keep logo and important subject matter inside a safe zone of at least 80px for 1200x630 images.
- No fake UI metrics, no invented client names, no tiny generated text as the only source of information.
- If text is needed, keep it minimal and repeat the important wording in the surrounding HTML or caption.

Ready to copy

Pick the job, then use the system.

Start from a recipe

Pick the right logo

Keep it builder-led

Use brand-safe prompts

Same brand DNA, dark-mode system.

Designer-built systems

Wide but controlled

Subtle reveal, never dependency

Clear sources of truth

Brand colors and runtime aliases.

Official Brand Colors

Runtime Website Tokens

Semantic Color Roles

Spacing Rhythm

Shape, Elevation, Motion, Breakpoints

Logo usage that stays boringly correct.

Horizontal Reversed

Horizontal Full Color

Symbol Gradient

Download logos and source files from Brand Assets.

Reusable pieces for fast page builds.

Buttons

Section Headers

Cards

Tags

Forms

Prompt Panels

Accordions

Tables

CTA Bands

Component states and previews

Action hierarchy

Label, helper, error

Native accordion

Category chips

Useful, not decorative

AI Image Prompt Kit

One conversion job

Page structures with clear jobs.

Home Hero

Service Page

System Case Study

Blog Post

Library/Search

Resource Page

Reusable page structures with known decisions.

Service Page

System Case Study

Blog Post

Resource / Tool Page

Intake / Contact Flow

Practical, specific, builder-led.

Content defaults

Brand-safe image production, without fake details.

Default outputs

Production checklist

Use the public tools

Dark, cinematic, still usable.

#A3A39F on #111110

#6B6B68 on #111110

Gradient button with white text

Visible ring or strong border shift

At least 44px where practical

Reduced-motion content remains complete

No horizontal overflow or clipped labels

Informative alt text, decorative hidden video

Run before a public page goes live

Rule 1

Rule 2

Rule 3

Rule 4

Rule 5

Rule 6

Keep the system in sync.

Update these together when their responsibilities overlap

Copy-ready source references.

Runtime token block

Semantic aliases