Update component READMEs with consistent structure and improved docum…

…entation Co-authored-by: george.marshall <[email protected]>
MetaMask · georgewrmarshall · Jul 18, 2025 · Jul 18, 2025 · Jul 21, 2025 · Jul 21, 2025
commit 3cd55ea7875dd268c2e1bf68de4d39e945ebacb9
@@ -1,160 +1,174 @@
 # AvatarAccount
 
-The `AvatarAccount` component is reserved for representing accounts inside of an avatar.
+AvatarAccount is used to render account avatars within an interface.
 
-_Developer Note: It extends the functionality of [`AvatarBase`](../AvatarBase/) by incorporating an Account and severity levels, making it useful for visually representing statuses, alerts, or simply user avatars with Accounts._
+```tsx
+import { AvatarAccount } from '@metamask/design-system-react-native';
 
----
+<AvatarAccount address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8" />;
+```
 
 ## Props
 
-### `variant`
-
-Optional prop to control the variant of the avatar account.
-
-| TYPE                   | REQUIRED | DEFAULT                         |
-| :--------------------- | :------- | :------------------------------ |
-| `AvatarAccountVariant` | No       | `AvatarAccountVariant.Jazzicon` |
-
-Available severities:
-
-- `Jazzicon`
-- `Blockies`
-- `Maskicon`
-
----
-
-### `address` (Required)
+### `address`
 
 Required address used as a unique identifier to generate the AvatarAccount art.
 
-| TYPE     | REQUIRED | DEFAULT |
-| :------- | :------- | :------ |
-| `string` | Yes      | `N/A`   |
-
----
-
-### `blockiesProps`
-
-Optional props to be passed to the `Blockies` component when the variant is `Blockies`.
-
-| TYPE                     | REQUIRED | DEFAULT     |
-| ------------------------ | -------- | ----------- |
-| `Partial<BlockiesProps>` | No       | `undefined` |
+| TYPE | REQUIRED | DEFAULT |
+|------|----------|---------|
+| `string` | Yes | `undefined` |
 
-Used to customize the `Blockies` identicon, such as block size or color settings.
-
----
-
-### `jazziconProps`
+```tsx
+<AvatarAccount address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8" />
+```
 
-Optional props to be passed to the `Jazzicon` component when the variant is `Jazzicon`.
+### `variant`
 
-| TYPE                     | REQUIRED | DEFAULT     |
-| ------------------------ | -------- | ----------- |
-| `Partial<JazziconProps>` | No       | `undefined` |
+Optional prop to control the variant of the avatar account.
 
-Used to customize the `Jazzicon` identicon, such as diameter or address seed.
+Available variants:
 
----
+- `AvatarAccountVariant.Jazzicon` (default)
+- `AvatarAccountVariant.Blockies`
+- `AvatarAccountVariant.Maskicon`
 
-### `maskiconProps`
+| TYPE | REQUIRED | DEFAULT |
+|------|----------|---------|
+| `AvatarAccountVariant` | No | `AvatarAccountVariant.Jazzicon` |
 
-Optional props to be passed to the `Maskicon` component itself.
+```tsx
+<AvatarAccount 
+  address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
+  variant={AvatarAccountVariant.Blockies}
+/>
+```
 
-| TYPE                     | REQUIRED | DEFAULT     |
-| ------------------------ | -------- | ----------- |
-| `Partial<MaskiconProps>` | No       | `undefined` |
+### `size`
 
-Useful for forwarding additional `SvgProps`, accessibility attributes, or animation styles.
+The size of the AvatarAccount.
 
----
+Available sizes:
 
-### Other Props
+- `AvatarSize.Xs` (16px)
+- `AvatarSize.Sm` (24px)
+- `AvatarSize.Md` (32px)
+- `AvatarSize.Lg` (40px)
+- `AvatarSize.Xl` (48px)
 
-`AvatarAccount` supports all props from [`AvatarBase`](#) except `children`, `fallbackText`, and `fallbackTextProps`. This includes:
+| TYPE | REQUIRED | DEFAULT |
+|------|----------|---------|
+| `AvatarSize` | No | `AvatarSize.Md` |
 
-- `size` – Controls the avatar size. See [AvatarBase documentation](#) for details.
-- `shape` – Controls the avatar shape. See [AvatarBase documentation](#) for details.
-- `twClassName` – Additional Tailwind class names.
-- `style` – Override or extend style properties.
+```tsx
+<AvatarAccount 
+  address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
+  size={AvatarSize.Lg}
+/>
+```
 
----
+### `blockiesProps`
 
-## Accessibility
+Optional props to be passed to the Blockies component when the variant is Blockies.
 
-Since `AvatarAccount` typically represents an account-based avatar. it is important to ensure the component is usable by screen readers and assistive technologies. The following `react-native` accessibility props can be passed:
+| TYPE | REQUIRED | DEFAULT |
+|------|----------|---------|
+| `Partial<BlockiesProps>` | No | `undefined` |
 
-- **`accessibilityLabel`**: Use to describe the AvatarAccount.
-- **`accessibilityRole`**:
-  - If interactive (e.g., navigates to account details), set to `button` or another appropriate role.
-- **`accessibilityHint`**: Provide context if `AvatarAccount` triggers a navigation or action.
-- **`accessible`**: Set to `true` when the avatar is meaningful, so screen readers properly identify it. If the Account is strictly decorative or not essential, it can be set to `false`.
+```tsx
+<AvatarAccount 
+  address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
+  variant={AvatarAccountVariant.Blockies}
+  blockiesProps={{ scale: 3 }}
+/>
+```
 
----
+### `jazziconProps`
 
-## Usage
+Optional props to be passed to the Jazzicon component when the variant is Jazzicon.
 
-### Basic Usage
+| TYPE | REQUIRED | DEFAULT |
+|------|----------|---------|
+| `Partial<JazziconProps>` | No | `undefined` |
 
 ```tsx
-import React from 'react';
-import AvatarAccount, {
-  AvatarAccountSeverity,
-} from '@metamask/design-system-react-native';
-
-<AvatarAccount address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8" />;
+<AvatarAccount 
+  address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
+  variant={AvatarAccountVariant.Jazzicon}
+  jazziconProps={{ diameter: 40 }}
+/>
 ```
 
----
+### `maskiconProps`
+
+Optional props to be passed to the Maskicon component when the variant is Maskicon.
 
-### Setting Variant
+| TYPE | REQUIRED | DEFAULT |
+|------|----------|---------|
+| `Partial<MaskiconProps>` | No | `undefined` |
 
 ```tsx
-<AvatarAccount
-  address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
-  variant={AvatarAccountVariant.Blockies}
-/>
-<AvatarAccount
-  address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
-  variant={AvatarAccountVariant.Jazzicon}
-/>
-<AvatarAccount
+<AvatarAccount 
   address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
   variant={AvatarAccountVariant.Maskicon}
+  maskiconProps={{ showBorder: true }}
 />
 ```
 
----
+### `twClassName`
 
-### Changing Size
+Use the `twClassName` prop to add Tailwind CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to:
 
-```tsx
-import { AvatarSize } from '@metamask/design-system-react-native';
+- Add new styles that don't exist in the default component
+- Override the component's default styles when needed
 
-<AvatarAccount
-  address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
-  size={AvatarAccountSize.Lg}
-/>;
-```
+| TYPE | REQUIRED | DEFAULT |
+|------|----------|---------|
+| `string` | No | `undefined` |
 
-See the [AvatarBase README](#) for more details on `size` and `shape`.
+```tsx
+import { AvatarAccount } from '@metamask/design-system-react-native';
 
----
+// Add additional styles
+<AvatarAccount 
+  address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
+  twClassName="border-2 border-primary-100"
+>
+  Custom Border
+</AvatarAccount>
 
-## Notes
+// Override default styles
+<AvatarAccount 
+  address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
+  twClassName="!bg-error-100"
+>
+  Override Background
+</AvatarAccount>
+```
 
-- `AvatarAccount` relies on [`AvatarBase`](#) for its foundational behavior.
-- The `variant` prop changes the AvatarAccount art style.
+### `style`
 
----
+Use the `style` prop to customize the component's appearance with React Native styles. For consistent styling, prefer using `twClassName` with Tailwind classes when possible, and use `style` for dynamic values or styles not available in Tailwind.
 
-## Contributing
+| TYPE | REQUIRED | DEFAULT |
+|------|----------|---------|
+| `StyleProp<ViewStyle>` | No | `undefined` |
 
-1. Add tests for new features.
-2. Update this README for any changes to the API.
-3. Follow the design system's coding guidelines.
+```tsx
+const styles = StyleSheet.create({
+  custom: {
+    marginVertical: 8,
+    marginHorizontal: 16,
+  },
+});
+
+export const StyleExample = () => (
+  <AvatarAccount 
+    address="0x9Cbf7c41B7787F6c621115010D3B044029FE2Ce8"
+    style={styles.custom}
+  />
+);
+```
 
----
+## References
 
-For questions, refer to the [React Native documentation](https://reactnative.dev/docs), the [AvatarBase documentation](#), or contact the maintainers of the design system.
+[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940)