chore: add AGENTS.md and conventions by amanabiy · Pull Request #4387 · cloudscape-design/components

amanabiy · 2026-03-26T16:59:25Z

Description

Adds AGENTS.md as a top-level entry point for AI coding agents working in this repo, along with supporting documentation in docs/.

Key changes:

AGENTS.md — setup, build, and run instructions tailored for agents, with pointers into docs/ for deeper guidance.
docs/CLOUDSCAPE_COMPONENTS_GUIDE.md — central index for component conventions, styling, testing, and internals. Designed to be reusable across related repos.
Additional docs linked from the guide covering code style, styling patterns, test authoring, and component API conventions.

I have other repositories reusing the CLOUDSCAPE_COMPONENTS_GUIDE.md for example take a look at this PR for chat-components repository.

Related links, issue #, if available: X2NaAdxtpFej rcDoAlynI8Zj

How has this been tested?

Verified locally that with considering all the feedbacks from the team, and running against our of predefined tests.

Review checklist

The following items are to be evaluated by the author(s) and the reviewer(s).

Correctness

Changes include appropriate documentation updates.
Changes are backward-compatible if not indicated, see CONTRIBUTING.md.
Changes do not include unsupported browser features, see CONTRIBUTING.md.
Changes were manually tested for accessibility, see accessibility guidelines.

Security

If the code handles URLs: all URLs are validated through the checkSafeUrl function.

Testing

Changes are covered with new/existing unit tests?
Changes are covered with new/existing integration tests?

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

codecov · 2026-03-26T17:17:03Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.45%. Comparing base (c8acad4) to head (1d29949).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4387   +/-   ##
=======================================
  Coverage   97.44%   97.45%           
=======================================
  Files         906      909    +3     
  Lines       26561    26637   +76     
  Branches     9582     9614   +32     
=======================================
+ Hits        25882    25958   +76     
  Misses        673      673           
  Partials        6        6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

pan-kot · 2026-03-30T08:05:57Z

docs/API_DOCS.md

+
+This project uses `@cloudscape-design/documenter` to generate API docs from JSDoc comments in component interface files (`src/<component>/interfaces.ts`).
+
+## Special Tags


We also have @awsuiSystem

docs/COMPONENT_CONVENTIONS.md

pan-kot · 2026-03-30T08:09:37Z

docs/COMPONENT_CONVENTIONS.md

+
+- Props interface: `${ComponentName}Props`, namespace sub-types under it (e.g. `${ComponentName}Props.Variant`)
+- Union types must be type aliases (no inline unions)
+- Array types must use `ReadonlyArray<T>`


Does it still? I think our updated documenter can actually handle readonly T[] - could we check it?

pan-kot · 2026-03-30T08:10:01Z

docs/COMPONENT_CONVENTIONS.md

+- Props interface: `${ComponentName}Props`, namespace sub-types under it (e.g. `${ComponentName}Props.Variant`)
+- Union types must be type aliases (no inline unions)
+- Array types must use `ReadonlyArray<T>`
+- Cast string props to string at runtime if rendered in JSX — React accepts JSX content there


What does this line mean?

It is part of our v3-development convention. It said. If you declared property as a string type, but then you also use it in JSX content (for example: <div>{option.label}</div>), you need to add additional cast to string in runtime, because React would accept JSX content there which allows customers to provide unsupported content.. I will remove it since it's confusing.

docs/COMPONENT_CONVENTIONS.md

pan-kot · 2026-03-30T08:15:46Z

docs/DEV_PAGES.md

@@ -0,0 +1,7 @@
+# Dev Pages
+
+Dev and test pages live in `pages/<component-name>/`. They are used for local development, integration tests, and visual regression tests.


Why do we say "dev and test pages" - instead of just "test pages" or "demo pages"? We sometimes add a -test suffix to pages used in integ tests, but that rule is not always followed.

pan-kot · 2026-03-30T08:16:50Z

docs/DEV_PAGES.md

+Dev and test pages live in `pages/<component-name>/`. They are used for local development, integration tests, and visual regression tests.
+
+## Rules
+- For visual regression content, either use `SimplePage` (handles heading, screenshot area, i18n, and layout) or wrap content in `ScreenshotArea`.


The mention of visual regression testing can be confusing. In this repo we don't run VR tests in GitHub - only in the internal pipeline.

docs/DIRECTORY_LAYOUT.md

pan-kot · 2026-03-30T08:18:35Z

docs/DIRECTORY_LAYOUT.md

+│       ├── generated           - generated code from style-dictionary
+│       └── styles              - base styles and SCSS-mixins
+│
+├── lib                         - build output


why is it necessary to describe the build output structure?

It helps with understanding the project structure and debugging build issues. This section was originally part of our CONTRIBUTING.md. I just moved it here for better organization.

docs/DIRECTORY_LAYOUT.md

docs/GENERAL_GUIDE.md

docs/INTERNALS.md

pan-kot · 2026-03-30T08:22:46Z

docs/RUNNING_TESTS.md

+
+## Test Types
+
+- **Build-tool tests** — test the build-tools code in a NodeJS context.


Do we really need to mention build-tool tests? We have a few of those, and those are touches very seldom.

At the same time, we can mention the a11y tests here. We have a util to run a11y checks in unit tests, and there are separate scripts to run a11y tests on the test pages.

pan-kot · 2026-03-30T08:24:57Z

docs/RUNNING_TESTS.md

+When component APIs change, you may need to update test snapshots. Use the `-u` flag to update snapshots:
+
+```
+TZ=UTC  npx jest -u snapshot -c jest.unit.config.js src/


All snapshot tests are grouped inside global unit and integ folders, which means:

There is no need to run all unit tests to update snapshots

When design tokens are touched - one must run integ tests to update snapshots

Also, it is essential to mention that the project must be built with the full build (npm run build) before updating snapshots - so that documenter docs are generated.

pan-kot · 2026-03-30T08:25:35Z

docs/RUNNING_TESTS.md

+TZ=UTC  npx jest -u snapshot -c jest.unit.config.js src/
+```
+
+## Visual Regression Tests


We don't have these in the components repo atm.

docs/WRITING_TESTS.md

pan-kot · 2026-03-30T08:29:44Z

docs/WRITING_TESTS.md

@@ -0,0 +1,28 @@
+# Writing Tests


Should we consider describing test utils separately from testing, either as part of component conventions or in a separate section? While we use test utils for internal testing - the main purpose of test utils is different - they are part of our contract.

At the same time, I don't think we should have separate running tests and writing tests guide, as there is a lot of similar info - I recommend combining the two.

Separating the test-utils makes sense to me. I will move it the component conventions.

The reason I kept them separate is that the writing tests guide is meant to be shared across repositories, while the running tests part is repo-specific. for example here through the CLOUDSCAPE_COMPONENTS_GUIDE.md. Therefore I think it's better if we keep it separate for now.

pan-kot · 2026-03-30T08:31:33Z

AGENTS.md

+npm install
+```
+
+## Building


These are useful instructions. Should we have them in our general docs somewhere? I think the agents.md should ideally only give references to other docs.

amanabiy requested a review from a team as a code owner March 26, 2026 16:59

amanabiy requested review from ernst-dev and removed request for a team March 26, 2026 16:59

amanabiy added 3 commits March 26, 2026 18:00

test: testing ai instructions

d92a591

chore: improve docs

11af693

chore: improve docs according to feedback

92871de

amanabiy force-pushed the dev-v3-amanabiy-ai-instructions branch from 9365e0d to 92871de Compare March 26, 2026 17:00

chore: removing relations in docs/ files

6bb8323

amanabiy deployed to dev-pages-react18 March 26, 2026 17:16 — with GitHub Actions View deployment

amanabiy deployed to dev-pages-react16 March 26, 2026 17:16 — with GitHub Actions View deployment

chore: clean up docs to make it more structured

17d9487

amanabiy force-pushed the dev-v3-amanabiy-ai-instructions branch from 2daa3b6 to 17d9487 Compare March 27, 2026 08:33

chore: rename file to make it more descriptive

1f02410

amanabiy deployed to dev-pages-react18 March 27, 2026 08:44 — with GitHub Actions View deployment

amanabiy deployed to dev-pages-react16 March 27, 2026 08:44 — with GitHub Actions View deployment

amanabiy added 2 commits March 27, 2026 10:15

chore: simplify by removing file paths

a4b8853

chore: centralize the import for the common guide

26d495c

amanabiy deployed to dev-pages-react18 March 27, 2026 10:26 — with GitHub Actions View deployment

amanabiy deployed to dev-pages-react16 March 27, 2026 10:26 — with GitHub Actions View deployment

chore: modularize CONTRIBUTING.md

5a85f8a

amanabiy force-pushed the dev-v3-amanabiy-ai-instructions branch from 95a048e to 5a85f8a Compare March 27, 2026 13:26

amanabiy requested a review from pan-kot March 27, 2026 13:28

amanabiy deployed to dev-pages-react18 March 27, 2026 13:36 — with GitHub Actions View deployment

amanabiy deployed to dev-pages-react16 March 27, 2026 13:36 — with GitHub Actions View deployment