Update button docs variant details
Purpose
The button variants are being paired down (see gitlab-org/gitlab-design#1263 (closed)) and we need to introduce the new Confirm button (getting added to GitLab UI in gitlab-org/gitlab-ui!1935 (merged)), and mention which variants will be deprecated.
This update will:
- Clarify button variants and their use.
- Note which buttons will be deprecated.
- Include the latest examples from GitLab UI.