VINASIGagents

Agent entry point

For SI agents

A predictable path to project context, the relevant UI rule, and the correct implementation source.

This design system is a draft

Do not present its guidance as approved VINASIG policy or apply it to another project without checking that project's instructions.

Default visual direction

Bright Playful Minimalism

Use the design system's draft direction unless the task or an approved product decision specifies something more specific.

  • Build on a flat, content-led, minimal layout with light neutral surfaces.
  • Use identity color selectively, and keep pixel or rounded-square details sparse.
  • Add illustration only when it helps explain the content or a user action.
  • Do not add generic gradients, oversized headings, repeated cards without distinct content, decorative pills, badges, or filler by habit. Use cards when they clarify a real content group.
  • Borrow from Apple, GitHub, or Duolingo only when asked for a specific quality. Do not copy or mix their complete visual styles.
Read the full visual direction 

Required website completion check

Do not forget the favicon

A logo in the page header does not configure the icon shown in browser tabs, bookmarks, and other browser surfaces.

Before closing a website task

  • Inspect the shared document head or layout and confirm favicon references exist.
  • Use the official 16 × 16, 32 × 32, and 48 × 48 px exports when they are available.
  • Check that the icon URLs account for the deployment base path and that each file is included in the output.
  • Report a missing source icon instead of silently skipping it or drawing a substitute.

VINASIG favicon references

<link rel="icon" type="image/png" sizes="16x16" href="/brand/favicons/favicon-16.png" />
<link rel="icon" type="image/png" sizes="32x32" href="/brand/favicons/favicon-32.png" />
<link rel="icon" type="image/png" sizes="48x48" href="/brand/favicons/favicon-48.png" />
See the logo guide and supplied favicon files 

Required UI completion check

A styled closed control is only half of a custom dropdown. The open options panel can still fall back to browser or operating-system styling.

Before closing a UI task

  • Open every select control and dropdown touched by the task. Inspect the actual options panel.
  • When the design calls for custom UI, style the trigger and popup states together.
  • Preserve visible focus, keyboard selection, Escape-to-close, and accessible selected-state announcements.
  • Check that the popup stays attached to its control and fits on narrow screens.

Use the component specification

Read docs/components/README.md before implementing a single-select dropdown. Prefer an existing accessible component. Do not ship a visual-only custom control.

View dropdown guidance and states 

Recommended workflow

Load context in a few deliberate steps

Use the narrowest source that answers the task, then check its authority and status.

Step 01

Read the project guide

Start with the consuming website's `AGENTS.md`, then this repository's root `AGENTS.md` if the task calls for this system.

Step 02

Find the matching rule

Use the matching foundation, component, pattern, or UI element entry. Inspect its rendered example and check the platform label before applying it.

Step 03

Check status and source

Follow approved rules when available. Mark these prototype rules as draft and keep token changes in the source file.

Required interface review

A successful build still needs a browser check

Recent Reddit reports describe generic card-heavy layouts, text overflow on small screens, mismatches with visual references, changed control types, and fixes that introduce new defects. Other users report better results with clear design rules and screenshots. These are anecdotes, not failure rates.

Before coding

  • Read the project brief, relevant UI guidance, tokens, assets, and existing components.
  • Write down the changed route, user action, content edge cases, viewport sizes, and important state transitions.
  • Record the visual direction in concrete layout, color, type, and shape choices. Keep the project identity and do not fill gaps with a generic generated style.
  • Do not add version labels, draft badges, prototype footers, repeated navigation, or machine-readable index links unless requested, required, or useful to a defined user need. Keep required attributions and legal notices.
  • When a screenshot or URL is supplied, record what must match and preserve the intended control types and behavior.

Before closing the task

  • Inspect the real page around 1440, 1024, 768, 390, and 320 CSS px where practical.
  • Compare the rendered result with supplied references at the same viewport. Check small-screen text, overflow, placement, and behavior.
  • Check long content, zoom, open dropdowns, visible focus, keyboard behavior, and page overflow.
  • Inspect changed controls in the browser accessibility tree. Confirm each has the right role, accessible name, and selected or expanded state.
  • Check actual text and icon contrast on rendered backgrounds, plus reduced-motion behavior where relevant.
  • Fix clipping at its source. Do not hide layout defects with global overflow rules.
  • If the same visual issue remains after two scoped fixes, stop and diagnose the layout or conflicting styles before adding another override.
  • Recheck affected routes after the final change and report anything that could not be verified.

Research and standards

Recent measurements found unnamed controls in sampled websites and structural accessibility issues in a separate frontend audit. A benchmark also found automated accessibility violations in pages generated by GPT-5.6 Luna. These studies have narrow methods and do not predict every project. They support checking semantics and browser output rather than trusting model choice or screenshots alone.

Read WCAG 2.2 Read the accessibility benchmark Read the recent model benchmark Read the accessibility tree measurement Read the generated frontend audit Read the design homogenization study 

Full checklist and source notes

Read docs/agents/ui-quality.md for the complete workflow, evidence limits, project-specific findings, recent Reddit reports, and annotated sources.

Add to a website repository

Keep the context close to the code

Import the shared working standard, then record the design source commit and the project's approved exceptions.

# AGENTS.md in a consuming website repository

## VINASIG working and interface guidance
- Import a reviewed VINASIG/agent-standards snapshot with its approved digest.
- Keep the generated AGENTS.md block, local manifest and .agents/skills files.
- Start a fresh agent session to check discovery of the installed skills.
- Record the VINASIG/web-design-system source commit used by this project.
- Read the matching foundation, component specification and rendered example.
- Review source tokens and components against the project's approved design.
- Current design guidance is draft and requires owner approval.

A URL or Markdown link alone does not import instructions or install components. This repository has no published design-system npm package.

Read the shared standards integration procedure 

Write agent-readable rules

Make each instruction direct and traceable

  • RequiredA rule that applies whenever its stated scope is met.
  • PreferredThe recommended choice. Document the reason when a project needs an exception.
  • OptionalAn allowed option that the implementation can choose when useful.

For every rule, name its scope, source file, and approval status. Include a small working example when a rule affects code or interaction.

Source map

Where to find the canonical information

Project and agent context

AGENTS.md routes shared working rules and required project context. docs/agents/project-guide.md retains the complete design guide.

SI agent UI review

docs/agents/ui-quality.md defines the research-backed quality workflow and completion gate for interface work.

Brand identity

docs/brand/README.md lists logo variant facts, export paths, and draft usage guidance.

Design guidance

docs/ contains source specifications for foundations, components, and patterns.

UI element library

docs/elements/catalog.json defines all 81 entries. Open the matching rendered example and check its platform label before using it.

Implementation tokens

src/styles/tokens.css defines identity colors, semantic roles, an optional extended palette for specific needs, shared interface tokens, and the locally hosted typeface.

Published index

/llms.txt provides a compact navigation map for tools that can fetch the docs site.