diff --git a/README.md b/README.md
index 9756589..9dfc8aa 100644
--- a/README.md
+++ b/README.md
@@ -6,24 +6,69 @@ Links: **[ilw-card in Builder](https://builder3.toolkit.illinois.edu/component/i
## Overview
-A 1-3 paragraph explanation of what the component does and how it presents.
+A card component that can be used as a container for grouping information, reminiscent of a physical
+note or playing card.
+
+By default, the card is a white box with a dark border, limited in width, showing the content inside of it. There are
+several variations:
+
+- The top of the card can have an image using `slot="image"`, or an icon using `slot="icon"`.
+- The whole card can be made clickable using the attribute `clickable`.
+- Text content can be centered using the `centered` attribute.
+- Color themes for `gray`, `blue`, `orange`, `blue-gradient` and `orange-gradient`. For example, `theme="blue"`.
## Code Examples
+### Basic card with buttons
+
+```html
+
+ Student Life
+ Animal sciences students extend their learning and career networks beyond the classroom.
+
+
+```
+
+### Card with an image
+
```html
-
+
+ 
+ Student Life
+ Animal sciences students extend their learning and career networks beyond the classroom.
+ Learn More About Student Life
+
```
-## Accessibility Notes and Use
+### Clickable card
+
+A clickable card uses the first link found in the contents as the primary link to use for the whole
+card. When using this form, do not wrap the whole contents of the card in a link, that is done automatically.
+
+A clickable card can have additional buttons or links that function as normal. Clicking the card outside of
+those will utilize the first link in the contents.
+
+```html
+
+
+
+ Animal sciences students extend their learning and career networks beyond the classroom.
+ Contact Us
+
+```
-Consider accessibility, both for building the component and for its use:
+## Accessibility Notes
-- Is there sufficient color contrast?
-- Can the component be fully understood without colors?
-- Does the component need alt text or ARIA roles?
-- Can the component be navigated with a keyboard? Is the tab order correct?
-- Are focusable elements interactive, and interactive elements focusable?
-- Are form fields, figures, fieldsets and other interactive elements labelled?
+- **Images and icons** on cards should generally be decorative with an empty `alt=""` attribute. If you do need an image
+ that needs to be described, consider placing it below the heading. If it's at the top with an alt text,
+ it may be confusing for screen readers if it comes before the title of the card.
+- **Centered text** can be harder to read, so avoid longer card text that's centered.
+- Make sure **links and buttons** are descriptive, using `ilw-sr-only` if needed to add context.
## External References