From 30f4e08309947b61e12b5cea7ca624ad9f142317 Mon Sep 17 00:00:00 2001
From: Harsh <6162866+harsh62@users.noreply.github.com>
Date: Fri, 3 Jul 2026 12:16:59 -0400
Subject: [PATCH] docs(develop-with-ai): add AWS Blocks steering-file recipe +
fix modal icons
Adds an "AWS Blocks integration" section to the steering-files page with
a per-tool recipe (Claude Code, Cursor, Kiro) so AI coding assistants
follow the Blocks integration patterns. All claims verified against the
aws-blocks source (create-blocks-app scaffolds AGENTS.md; backend in
aws-blocks/index.ts with CognitoVerifier + requireAuth; blocks:generate-client;
import { api } from aws-blocks; npm run sandbox).
Also folds in the modal icon fix from #8609: replace the puzzle emoji
with IconStar and size both feature-point icons consistently.
Rebuilt on latest main so the aws-blocks internal links (merged in #8606)
resolve, clearing the earlier CheckPRLinks failure.
---
src/components/Modal/Modal.tsx | 11 ++-
.../develop-with-ai/steering-files/index.mdx | 71 ++++++++++++++++++-
2 files changed, 78 insertions(+), 4 deletions(-)
diff --git a/src/components/Modal/Modal.tsx b/src/components/Modal/Modal.tsx
index e6cc594460d..3cf451feb5c 100644
--- a/src/components/Modal/Modal.tsx
+++ b/src/components/Modal/Modal.tsx
@@ -65,9 +65,9 @@ export const Modal = (_props: ViewProps) => {
aria-hidden="true"
className="modal-key-point-left"
textAlign="center"
- fontSize="xxxl"
+ fontSize="xxl"
>
- 🧩
+
@@ -81,7 +81,12 @@ export const Modal = (_props: ViewProps) => {
-
+
diff --git a/src/pages/[platform]/develop-with-ai/steering-files/index.mdx b/src/pages/[platform]/develop-with-ai/steering-files/index.mdx
index 647159ec73d..304d68d0714 100644
--- a/src/pages/[platform]/develop-with-ai/steering-files/index.mdx
+++ b/src/pages/[platform]/develop-with-ai/steering-files/index.mdx
@@ -3,7 +3,7 @@ import { getCustomStaticPath } from '@/utils/getCustomStaticPath';
export const meta = {
title: 'Steering files',
description:
- 'Configure project-level context files to guide AI coding assistants when building Amplify applications.',
+ 'Configure project-level context files to guide AI coding assistants when building Amplify applications, including AWS Blocks integration patterns.',
platforms: [
'android',
'angular',
@@ -118,6 +118,75 @@ globs: amplify/**/*
Download these files and place them in a `context/` folder in your project root.
+## AWS Blocks integration
+
+If your project uses [AWS Blocks](/[platform]/build-a-backend/aws-blocks/) alongside Amplify, add steering rules so assistants follow the integration patterns — defining backend capability in `aws-blocks/index.ts`, authenticating with your Amplify Cognito pool, and calling the generated typed client instead of constructing requests by hand. This mirrors the `AGENTS.md` that `create-blocks-app` scaffolds into your project.
+
+The same guidelines work across assistants — use the file format your tool expects.
+
+
+
+Add to your `CLAUDE.md` file in the project root:
+
+```markdown title="CLAUDE.md"
+# AWS Blocks integration
+
+This Amplify Gen 2 project uses AWS Blocks for backend capabilities.
+
+- Define backend APIs, auth, and data in `aws-blocks/index.ts` using Building Blocks.
+- Use Building Blocks (`KVStore`, `DistributedTable`, `FileBucket`, etc.) for all persistence — never local files, in-memory arrays, or local databases.
+- Authenticate protected operations with `CognitoVerifier` and `requireAuth(context)`; it verifies the Amplify-issued Cognito token. Do not create a second user pool.
+- After changing the API surface, regenerate the client with `npm run blocks:generate-client`, then import and call the typed `api` (for example, `import { api } from 'aws-blocks'`). The JSON-RPC transport is invisible — do not build request payloads by hand.
+- Deploy and test Amplify and Blocks together with `npm run sandbox`.
+```
+
+
+
+
+
+Create a rules file at `.cursor/rules/aws-blocks.mdc`:
+
+```markdown title=".cursor/rules/aws-blocks.mdc"
+---
+description: AWS Blocks integration for Amplify
+globs:
+ - "aws-blocks/**"
+ - "amplify/**"
+---
+
+# AWS Blocks integration
+
+This Amplify Gen 2 project uses AWS Blocks for backend capabilities.
+
+- Define backend APIs, auth, and data in `aws-blocks/index.ts` using Building Blocks.
+- Use Building Blocks for all persistence — never local files, in-memory arrays, or local databases.
+- Authenticate protected operations with `CognitoVerifier` and `requireAuth(context)`; it verifies the Amplify-issued Cognito token. Do not create a second user pool.
+- After changing the API surface, regenerate the client with `npm run blocks:generate-client`, then import and call the typed `api`. The JSON-RPC transport is invisible — do not build request payloads by hand.
+- Deploy and test Amplify and Blocks together with `npm run sandbox`.
+```
+
+
+
+
+
+Create a steering file at `.kiro/steering/aws-blocks.md`:
+
+```markdown title=".kiro/steering/aws-blocks.md"
+# AWS Blocks integration
+
+This Amplify Gen 2 project uses AWS Blocks for backend capabilities.
+
+- Define backend APIs, auth, and data in `aws-blocks/index.ts` using Building Blocks.
+- Use Building Blocks for all persistence — never local files, in-memory arrays, or local databases.
+- Authenticate protected operations with `CognitoVerifier` and `requireAuth(context)`; it verifies the Amplify-issued Cognito token. Do not create a second user pool.
+- After changing the API surface, regenerate the client with `npm run blocks:generate-client`, then import and call the typed `api`. The JSON-RPC transport is invisible — do not build request payloads by hand.
+- Deploy and test Amplify and Blocks together with `npm run sandbox`.
+```
+
+
+
+To add AWS Blocks to your project in the first place, see [Add AWS Blocks to your Amplify project](/[platform]/build-a-backend/aws-blocks/get-started/).
+
## Tips for effective steering
- **Be specific about imports** — Tell the assistant which packages to import from (`@aws-amplify/backend` for backend, `aws-amplify` for frontend)