docs: added guidelines for facades and traits

[kumsmrit]

Issue # (if applicable)

Closes #.

Reason for this change

The existing design/mixins-facades-traits.md describes the architectural relationship between Facades, Traits, and Mixins, and docs/DESIGN_GUIDELINES.md covers when to use each building block. However, Facades and Traits lack a dedicated implementation guideline.
A new docs/FACADES_AND_TRAITS_DESIGN_GUIDELINES.md provides implementation guidance for Facades and Traits, covering the structural pattern (factory method, private constructor, public methods), naming conventions, project structures, how to use Facades and Traits in construct interfaces, and testing requirements.

Description of changes

• Created docs/FACADES_AND_TRAITS_DESIGN_GUIDELINES.md - dedicated design guideline for Facades and Traits, covering their key characteristics
• Updated other design to reference this new doc for Facades-and-Traits guidelines.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[github-actions]

👋 It looks like your PR description follows the template but is missing a valid issue number in the first section.

PRs without a linked issue will receive lower priority for review and merging. Please update the description to include a reference like Closes #123. If no existing issue matches your change, create one first.

[kumvprat]

Added a few inline comments

Overall the new guidelines do clear a lot about facades and traits, as well how they work with each other.

[kumvprat]

Based on my understanding, a facade uses a trait directly to manipulate the external consumers like done here with the IEncryptedResource trait which grants permission to the grantee to use the kms key for decryption

Any reason we don't do the same for the policyResource variable here which is again a type of trait IResourceWithPolicyV2?
Maybe this is just an example but do we want to promote using only traits inside a facade or is that just a loose guidance

[kumsmrit]

Both policyResource and encryptedResource are traits consumed by the Facade - the difference is in what each trait's contract provides:

• IResourceWithPolicyV2 has addToResourcePolicy() which accepts a statement — it's passed into Grant.addToPrincipalOrResource because the Grant framework needs to decide whether to use the
  principal's policy or the resource's policy. Calling it directly would bypass that decision.
• IEncryptedResource provides single self-contained grantOnKey() - it finds the KMS key and grants on it. No decision logic needed, so the Facade calls it directly.

[kumvprat]

Got it

So the facade author would need enough context to make this decision which given the fact that facades are per resource/service is a reasonable assumption.(Author should know enough about the service and it's dependent services to make decisions when designing a facade)

[kumvprat]

When adding new traits do we just implement the factory here or the trait itself ?

If trait is not implemented here what is the correct location for a trait for any given module/L1 resource?

[kumsmrit]

Currently both trait interfaces (IResourceWithPolicyV2, IEncryptedResource) live in aws-iam/lib/grant.ts because they are both IAM-related.
The general principle would be: the trait interface and registry live in the module most closely associated with the capability (e.g., an IAM-related trait → aws-iam)

The per-service factory implementations goes in lib/private/default-traits.ts of the service module.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-05-21 10:48 UTC · Rule: default-squash
• ✅ Checks passed · in-place
• ✅ Merged — 2026-05-21 11:34 UTC · at cbfc5260a0fdb94df192504f911101053a7e0bfc · squash

This pull request spent 46 minutes 28 seconds in the queue, including 45 minutes 55 seconds running CI.

Required conditions to merge

• #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  • docs: added guidelines for facades and traits #37860
• #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • docs: added guidelines for facades and traits #37860
• any of [🛡 GitHub branch protection]:
  • check-success = validate-pr
  • check-neutral = validate-pr
  • check-skipped = validate-pr
• any of [🛡 GitHub branch protection]:
  • check-success = build
  • check-neutral = build
  • check-skipped = build

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.