apply-digital-agency-design-system

Apply the Digital Agency Design System

Select only the necessary rationale from the approved official Markdown snapshot to fulfill the request. Separate routine work from checking for official updates, and do not activate update candidates without the user's approval. Hereafter, <skill-root> is replaced with the absolute path of the directory containing this SKILL.md. Hereafter, <python> is replaced with the command used to execute Python 3.10 or later. On macOS and Linux, this is typically python3; on Windows, it is typically py -3.

Information Boundaries

• The active_snapshot.path referenced in references/source-manifest.json is the active snapshot used for routine work.
• The source-index.json of the active snapshot, references/task-index.md, and references/foundation-map.md are derived materials. Verify their official meaning by consulting the corresponding Markdown files within the active snapshot.
• Official Markdown files are reconstructions intended for AI reference and are not a complete substitute for the official website. If a necessary description is missing from local materials, report it as an unverified item.
• This skill is unofficial and does not imply provision, approval, affiliation, or endorsement by the Digital Agency.
• The current state of an existing project is determined by examining CSS variables, theme settings, common styles, and common components. Do not duplicate them within the skill.
• Creation, modification, and review are categories of operational authority. New creation, existing modification, and individual components are categories of material selection and must not be confused.

Update Deadline Check at Startup

First, execute the following command. This command reads only local files and does not connect to the network.

<python> <skill-root>/scripts/manage_upstream.py status

Keep the status value from the output as status_at_start for the duration of the request.

• fresh: Proceed with routine work without showing an update notice.
• due, never_checked, unknown: Continue routine work without stopping, and re-check the status at the end.
• If the user explicitly states from the beginning something like "Check for the latest version," treat the explicit request as consent for external confirmation and proceed to the maintenance procedure.

The deadline is determined as 30 days from last_successful_check_at. Do not use the proposal date, failure date, or derived next check date as the starting point for the deadline.

Routine Work

1. Categorize the request as creation, modification, or review, and determine the permitted scope of operations.
2. Check the target's technical composition, existing styles, brand constraints, and screen structure.
3. Determine the material selection path in the following order of priority.
   • If the target is limited to a single UI component and its states, treat it as an individual component.
   • If common styles already exist, treat it as an existing modification.
   • Otherwise, treat it as new creation.
4. Select the target document from references/task-index.md. If none apply, search the active snapshot using the following command.

<python> <skill-root>/scripts/search_guidance.py \
  --query '<separate search terms with spaces>' \
  --manifest-file <skill-root>/references/source-manifest.json

5. Use references/foundation-map.md according to the material selection path.
   • New creation: Divide into 8 categories, adopted, excluded, or pending, and read the official Markdown for categories where values are determined.
   • Existing modification: Investigate existing values first, read only the affected categories, and divide them into retention, migration, or intentional deviation.
   • Individual component: Read only the existing common criteria, the target component, and the affected basic design. Do not re-determine common values within the component.
6. Distinguish between official options, default values, examples, principles, requirements, and fixed values, and map adopted values to their rationale.
7. Implement using the existing technical composition. Do not apply official examples as universal fixed values, and do not relax official requirements as mere visual preferences.
8. Depending on the target, verify multiple screen widths, keyboard operation, focus, state changes, zoom, and reflow.
9. For review requests, do not modify files; return only findings with rationale.

Completion Report for Routine Work

Report the following concisely:

• Reference version: Snapshot ID from source-manifest.json, Digital Agency Design System version, Markdown publication date.
• Verification scope: Official documents read and checks performed.
• Unverified items: Aspects not checked, such as actual devices, assistive technologies, or external live pages.
• Deviations: Content changed from official examples or recommendations for project-specific reasons.

Only if the startup state was due, never_checked, or unknown, re-run status immediately before reporting. If it has not become fresh due to another process, propose an update check once at the end of the final report.

More than 30 days have passed since the last official update check. This task was completed with the current approved version. Would you also like to perform an update check?

For never_checked or unknown, do not specify the number of elapsed days; instead, indicate the reason. Proposing alone does not involve external communication or state updates. Even if the user declines, the refusal time is not saved, so the proposal will be made again in subsequent sessions until a successful check occurs.

Confirming Official Updates

Execute the following only if the user agrees. Append --network-approved only after confirming the user's consent. If explicitly checking for the latest version even though less than 30 days have passed, add --force.

Let the default auto fetch backend handle the acquisition. If ax is found, auto delegates fetching the official page, extracting links, and saving the ZIP to ax. If not found, it uses the Python standard library. ax is recommended but optional; its absence should not be a prerequisite for the update check. The ax path validates the final URL after redirects but cannot validate intermediate destinations before communication. If intermediate destinations also need to be pre-restricted, use --fetch-backend stdlib. If a selected backend fails, do not silently switch to another backend. Post-acquisition verification of URL, size, ZIP format, hash calculation, diff creation, and state saving are performed in Python. Add --fetch-backend ax or --fetch-backend stdlib only to fix the method for testing, etc.

<python> <skill-root>/scripts/manage_upstream.py check \
  --network-approved

• unchanged: Update the successful check timestamp and report the fetch backend and no changes.
• candidate_created or candidate_exists: Report the fetch backend, candidate ID, acquisition source, hash, and counts of additions, changes, and deletions.
• skipped_fresh: Report that the external check was skipped because less than 30 days have passed.
• On failure: Do not change last_successful_check_at or the active snapshot; report the failed acquisition source and reason.

Do not treat consent to external confirmation as approval for adopting a candidate. If a candidate is found but verification of the official source and saving the candidate is complete, update the successful check timestamp.

Manual ZIP Acquisition

Only if automatic acquisition ultimately fails and check identifies the official ZIP URL and can guide manual acquisition, propose this procedure as a last resort. If it fails before identifying the URL, do not guess the acquisition source from the URL or filename; report only the failure.

Show the following content to the user:

Automatic ZIP acquisition failed. You can obtain it manually from the following official URL:
<Official ZIP URL>

Please save the ZIP to any folder. After saving, provide the absolute path including the filename.
The received ZIP will be verified without connecting to the network and saved as an update candidate. Switching to the active version will be confirmed separately.

Once the user provides the absolute path, execute the following. If only a relative path is known, confirm the absolute path before executing.

<python> <skill-root>/scripts/manage_upstream.py import-archive \
  --archive-file '<Absolute path to ZIP>'

import-archive links the local ZIP to the official URL recorded at the time of failure, and performs standard size, ZIP format, internal path, Markdown collection, hash verification, and candidate creation without connecting to the network. It does not modify or delete the original ZIP. Local import is not treated as a successful external check; it does not update last_successful_check_at or the confirmed contract version. Even if the result is candidate_created or candidate_exists, it is not automatically promoted; proceed to "Evaluating and Promoting Update Candidates."

If more than 30 days have passed since the official URL was identified, or if the update contract has changed, do not bypass the import; instead, request new consent for the update check. If manual acquisition or local import fails, do not change last_successful_check_at or the active snapshot.

Evaluating and Promoting Update Candidates

1. Read candidate-manifest.json and diff-summary.json within the candidate.
2. Verify the candidate with verify_snapshot.py.

The default storage location for candidates is candidates within the per-user state directory.

<python> <skill-root>/scripts/verify_snapshot.py \
  --snapshot-dir <state-dir>/candidates/<candidate-id>/snapshot \
  --index-file <state-dir>/candidates/<candidate-id>/source-index.json

3. Read the added, changed, and deleted official documents, and verify the impact on task-index.md and foundation-map.md.
4. Test representative creation, modification, and review requests with both the old version and the candidate version.
5. Present the candidate ID, semantic changes, derived material changes, and verification results to the user, and explicitly confirm adoption.
6. Only after the user approves by specifying the candidate ID, execute the following.

<python> <skill-root>/scripts/manage_upstream.py promote \
  --candidate-id '<candidate-id>' \
  --human-approved

Do not delete the previous snapshot after promotion. The promotion operation does not change last_successful_check_at.

Decision Rules

• Do not treat MANIFEST.md as the authoritative file list. Scan all Markdown files.
• Use the normalized source_url as the document ID. Since slug can duplicate between the body and update history, do not use it as a standalone ID.
• Do not create missing components, tokens, or class names as official specifications.
• If existing values conflict with official requirements, do not silently retain or replace them; show the impact and scope of modification.
• Do not declare full conformance to the Digital Agency Design System or WCAG based solely on visual inspection.
• When citing sources in public materials, read introduction/notices/index.md of the active snapshot.
• Save update status and candidates in a per-user local area, not intermixed with the skill's distribution files. Use the environment variable DADS_SKILL_STATE_DIR only to change the storage location.